routing-controllers-openapi

Runtime OpenAPI v3 schema generation for routing-controllers.

Installation

npm install --save routing-controllers-openapi

Usage

import { getMetadataArgsStorage } from 'routing-controllers'
import { routingControllersToSpec } from 'routing-controllers-openapi'

// Define your controllers as usual:
@JsonController('/users')
class UsersController {
  @Get('/:userId')
  getUser(@Param('userId') userId: string) {
    // ...
  }
  @HttpCode(201)
  @Post('/')
  createUser(@Body() body: CreateUserBody) {
    // ...
  }
}
// Generate a schema:
const storage = getMetadataArgsStorage()
const spec = routingControllersToSpec(storage)
console.log(spec)

prints out the following specification:

{
  "components": {
    "schemas": {}
  },
  "info": {
    "title": "",
    "version": "1.0.0"
  },
  "openapi": "3.0.0",
  "paths": {
    "/users/{userId}": {
      "get": {
        "operationId": "UsersController.getUser",
        "parameters": [
          {
            "in": "path",
            "name": "userId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {}
            },
            "description": "Successful response"
          }
        },
        "summary": "List users",
        "tags": ["Users"]
      }
    },
    "/users/": {
      "post": {
        "operationId": "UsersController.createUser",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateUserBody"
              }
            }
          },
          "description": "CreateUserBody",
          "required": false
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {}
            },
            "description": "Successful response"
          }
        },
        "summary": "Create user",
        "tags": ["Users"]
      }
    }
  }
}

Check

/sample

Configuration

routingControllersToSpec

export function routingControllersToSpec(
  storage: MetadataArgsStorage,
  routingControllerOptions: RoutingControllersOptions = {},
  additionalProperties: Partial = {}
): OpenAPIObject

routingControllerOptions

routePrefix

defaults

additionalProperties

info

components

Validation classes

Use class-validator-jsonschema to convert your validation classes into OpenAPI-compatible schemas:

import { validationMetadatasToSchemas } from 'class-validator-jsonschema'

// ...
const schemas = validationMetadatasToSchemas({
  refPointerPrefix: '#/components/schemas/',
})
const spec = routingControllersToSpec(storage, routingControllerOptions, {
  components: { schemas },
  info: { title: 'My app', version: '1.2.0' },
})

Decorating with additional keywords

Use the

@OpenAPI

import { OpenAPI } from 'routing-controllers-openapi'

@JsonController('/users')
export class UsersController {
  @Get('/')
  @OpenAPI({
    description: 'List all available users',
    responses: {
      '400': {
        description: 'Bad request',
      },
    },
  })
  listUsers() {
    // ...
  }
}

The parameter object consists of any number of properties from the Operation object. These properties are then merged into the spec, overwriting any existing values.

Alternatively you can call

@OpenAPI

(source: OperationObject, route: IRoute) => OperationObject

Multiple

@OpenAPI

decorators

A single handler can be decorated with multiple

@OpenAPI

  @OpenAPI({
    summary: 'This value will be overwritten!',
    description: 'This value will remain'
  })
  @OpenAPI({
    summary: 'This value will remain'
  })
  listUsers() {
    // ...
  }

Multiple

@OpenAPI

lodash/merge

Class

@OpenAPI

decorator

Using

@OpenAPI

@OpenAPI

@OpenAPI({
  security: [{ basicAuth: [] }], // Applied to each method
})
@JsonController('/users')
export class UsersController {
  // ...
}

Annotating response schemas

Extracting response types automatically in runtime isn't currently allowed by Typescript's reflection system. Specifically the problem is that

routing-controllers-openapi

@ResponseSchema

import { ResponseSchema } from 'routing-controllers-openapi'

@JsonController('/users')
export class UsersController {
  @Get('/:id')
  @ResponseSchema(User)
  getUser() {
    // ...
  }
}

@ResponseSchema

options

  @Post('/')
  @ResponseSchema(User, {
    contentType: 'text/csv',
    description: 'A list of created user objects',
    isArray: true
    statusCode: '201'})
  createUsers() {
    // ...
  }

contentType

statusCode

@ContentType

@HttpCode

options.isArray

true

ResponseSchema

Note that when using

@ResponseSchema

@JSONSchema

@ResponseSchema

@JSONSchema

@JSONSchema({responses: {
  '200': {
    'content': {
      'application/json': {
        schema: {
          '$ref': '#/components/schemas/Pet'
        }
      }
    }
  }
}})
@ResponseSchema(SomeResponseObject)
handler() { ... }

Multiple ResponseSchemas

Multiple ResponseSchemas with different status codes are supported as follows.

@ResponseSchema(Response1)
@ResponseSchema(Response2, {statusCode: '400'})

In case of multiple ResponseSchemas being registered with the same status code, we resolve them using the oneOf operator.

@ResponseSchema(Response1)
@ResponseSchema(Response2)

will generate

"200": {
  "content": {
    "application/json":{
      "schema": {
        "oneOf": [
          {$ref: "#/components/schemas/Response1"},
          {$ref: "#/components/schemas/Response2"}
        ]
      }
    }
  }
}

Supported features

• @Controller

  /

  @JsonController

  base route and default content-type

• options.routePrefix

• @Get

  ,

  @Post

  and other action decorators
• Parse path parameters straight from path strings and optionally supplement with

  @Param

  decorator
  • Regex and optional path parameters (e.g.

    /users/:id(\d+)/:type?

    ) are also supported

• @QueryParam

  and

  @QueryParams

• @HeaderParam

  and

  @HeaderParams

• @Body

  and

  @BodyParam

• Parse response keywords from

  @HttpCode

  and

  @ContentType

  values
• Global

  options.defaults.paramOptions.required

  option and local override with

  {required: true}

  in decorator params
• Parse

  summary

  ,

  operationId

  and

  tags

  keywords from controller/method names

Future work

• Support for routing-controller's authorization features

Feel free to submit a PR!

Related projects

• Inspired by tsoa and trafficlight
• Include your Mongoose models in the spec with mongoose-schema-jsonschema
• Generate JSON schema from your Typescript sources with typescript-json-schema
• openapi3-ts provides handy OpenAPI utilities for Typescript
• Convert OpenAPI 3 spec to Swagger 2 with api-spec-converter
• Generate Typescript interface definitions from SQL database schema with schemats