swagger-to-flowtype generates flow type aliases

swagger, flow

My team usually use swagger for API documentation. On my project, the definitions of API endpoints are not the simplest as object are nested and there is a vast number of definitions. On other hand, my currently project is using Flow type for static type checking of JavaScript. Flow type is a nice tool to determine the data type, and I believe that the static type checking works well, especially for team developing since type definitions would be a document and get more readability.

I thought migrating each definitions on swagger to Flow type manually is neither productive nor reusable. As my project was at an early development phase, I expected API documents would be updated frequently. So then I created swagger-to-flowtype, a command line tool as a npm module, to create type aliases of Flow automatically.

This tool works as follows.

  1. Parse a swagger file ( json or yaml )
  2. Correct definitions of each Object
  3. Determine the type alias
  4. Export a file named flowtype.js including determined types. You can also specify the exporting path as an option.

For instance, a swagger yaml file like below

...

definitions:
Order:
type: "object"
properties:
id:
type: "integer"
format: "int64"
petId:
type: "integer"
format: "int64"
quantity:
type: "integer"
format: "int32"
shipDate:
type: "string"
format: "date-time"
status:
type: "string"
description: "Order Status"
enum:
- "placed"
- "approved"
- "delivered"
complete:
type: "boolean"
default: false
xml:
name: "Order"
Category:
type: "object"
properties:
id:
type: "integer"
format: "int64"
name:
type: "string"
xml:
name: "Category"
...

will be

/ @flow
export type Order = {
id: number,
petId: number,
quantity: number,
shipDate: string,
status: string,
complete: boolean
};
export type Category = { id: number, name: string };

I believe this tool would be useful if you are using Flow type and swagger file as API documentation.

Here is the repo of swagger-to-flowtype. If you have any feedback, please let me know.

Like what you read? Give yayoc a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.