@flyweight.cloud/swaggerist

Swaggerist

Swaggerist is an opinionated and programmatic way to quickly build Swagger definitions for JSON API's. (Targetting Azure at the moment, so Swagger 2.0)

Pairs well with FlyWeight's OpenRoute framework for building Swagger API's on Azure

Build from JSON examples

Instead of building a Swagger Schema by hand, Swaggerist allows you to provide an example of the expected API output and builds a schema based on it.

Usage

npm install --save @flyweight.cloud/swaggerist

Simple example of a Swagger definition for an authenticated Azure Function API:

import Swaggerist, { bodyParamBuilder, pathParamBuilder, Responses, schemaBuilder, SwaggerSecuritySchemes } from "@flyweight.cloud/swaggerist"

const swaggerDetails = {
    info: {
        title: "My Swagger Def",
        description: "Example description of the Swagger Definition",
        version: "1.0.0",
    },
}

const swagger = Swaggerist.create(swaggerDetails)

// Add a security policy for Microsoft Oauth
swagger.addSecurityPolicy("oauth", SwaggerSecuritySchemes.MicrosoftOauth())

const userJson = {
    id: 1234,
    email: "[e-mail]",
    name: "Mark",
    address: {
        street: "123 Main St",
        city: "Atlanta",
        state: "GA",
        zip: "12345",
    }
}

swagger.post("/user", {
    operationId: "create_user",
    parameters: [...bodyParamBuilder("user", userJson)],
    responses: {
        "200": Responses.Success(schemaBuilder(userJson)),
        "500": Responses.ServerError,
    },
})

swagger.get("/users", {
    operationId: "get_users",
    responses: {
        "200": Responses.Success(schemaBuilder([userJson])),
        "404": Responses.NotFound,
    },
})

swagger.get("/user/{id}", {
    operationId: "get_user",
    parameters: [...pathParamBuilder(
        {
            id: { type: "string", description: "Users Id" },
        }),
    ],
    responses: {
        "200": Responses.Success(schemaBuilder(userJson)),
        "404": Responses.NotFound,
    },
})

console.log(
    JSON.stringify(
        swagger.generate("2.0", { scheme: "https", host: "localhost", base_path: "/api/my_az_function" }),
        null, 2
    )
)

Generated Swagger file:

{
  "swagger": "2.0",
  "info": {
    "title": "My Swagger Def",
    "description": "Example description of the Swagger Definition",
    "version": "1.0.0"
  },
  "schemes": [
    "https"
  ],
  "host": "localhost",
  "basePath": "/api/my_az_function",
  "paths": {
    "/user": {
      "post": {
        "operationId": "create_user",
        "parameters": [
          {
            "in": "body",
            "name": "user",
            "schema": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "format": "int32"
                },
                "email": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "address": {
                  "type": "object",
                  "properties": {
                    "street": {
                      "type": "string"
                    },
                    "city": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "zip": {
                      "type": "string"
                    }
                  }
                }
              },
              "example": {
                "id": 1234,
                "email": "[e-mail]",
                "name": "Mark",
                "address": {
                  "street": "123 Main St",
                  "city": "Atlanta",
                  "state": "GA",
                  "zip": "12345"
                }
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "schema": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "format": "int32"
                },
                "email": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "address": {
                  "type": "object",
                  "properties": {
                    "street": {
                      "type": "string"
                    },
                    "city": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "zip": {
                      "type": "string"
                    }
                  }
                }
              },
              "example": {
                "id": 1234,
                "email": "[e-mail]",
                "name": "Mark",
                "address": {
                  "street": "123 Main St",
                  "city": "Atlanta",
                  "state": "GA",
                  "zip": "12345"
                }
              }
            }
          },
          "500": {
            "description": "Server Error",
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string"
                },
                "code": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/users": {
      "get": {
        "operationId": "get_users",
        "responses": {
          "200": {
            "description": "Success",
            "schema": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer",
                    "format": "int32"
                  },
                  "email": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "address": {
                    "type": "object",
                    "properties": {
                      "street": {
                        "type": "string"
                      },
                      "city": {
                        "type": "string"
                      },
                      "state": {
                        "type": "string"
                      },
                      "zip": {
                        "type": "string"
                      }
                    }
                  }
                }
              },
              "example": [
                {
                  "id": 1234,
                  "email": "[e-mail]",
                  "name": "Mark",
                  "address": {
                    "street": "123 Main St",
                    "city": "Atlanta",
                    "state": "GA",
                    "zip": "12345"
                  }
                }
              ]
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string"
                },
                "code": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/user/{id}": {
      "get": {
        "operationId": "get_user",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "type": "string",
            "description": "Users Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "schema": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "format": "int32"
                },
                "email": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "address": {
                  "type": "object",
                  "properties": {
                    "street": {
                      "type": "string"
                    },
                    "city": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "zip": {
                      "type": "string"
                    }
                  }
                }
              },
              "example": {
                "id": 1234,
                "email": "[e-mail]",
                "name": "Mark",
                "address": {
                  "street": "123 Main St",
                  "city": "Atlanta",
                  "state": "GA",
                  "zip": "12345"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string"
                },
                "code": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    }
  },
  "securityDefinitions": {
    "oauth": {
      "type": "oauth2",
      "flow": "accessCode",
      "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
      "tokenUrl": "https://login.windows.net/common/oauth2/authorize",
      "scopes": {}
    }
  },
  "security": [
    {
      "oauth": []
    }
  ]
}