npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

routing-controllers-extended-openapi

v4.0.2

Published

Runtime OpenAPI v3 spec generation for routing-controllers-extended

Downloads

4

Readme

routing-controllers-extended-openapi

Runtime OpenAPI v3 schema generation for routing-controllers-extended.

Installation

npm install --save routing-controllers-extended-openapi

Usage

import { getMetadataArgsStorage } from 'routing-controllers-extended-extended'
import { routingControllersToSpec } from 'routing-controllers-extended-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 for a complete sample application.

Configuration

routingControllersToSpec has the following type signature:

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

routingControllerOptions refers to the options object used to configure routing-controllers. Pass in the same options here to have your routePrefix and defaults options reflected in the resulting OpenAPI spec.

additionalProperties is a partial OpenAPI object that gets merged into the result spec. You can for example set your own info or components keywords here.

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 decorator to supply your actions with additional keywords:

import { OpenAPI } from 'routing-controllers-extended-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 with a function of type (source: OperationObject, route: IRoute) => OperationObject, i.e. a function receiving the existing spec as well as the target route, spitting out an updated spec. This function parameter can be used to implement for example your own merging logic or custom decorators.

Multiple @OpenAPI decorators

A single handler can be decorated with multiple @OpenAPIs. Note though that since decorators are applied top-down, any possible duplicate keys are overwritten by subsequent decorators:

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

Multiple @OpenAPIs are merged together with lodash/merge which has a few interesting properties to keep in mind when it comes to arrays. Use the function parameter described above when strict control over merging logic is required.

Class @OpenAPI decorator

Using @OpenAPI on the controller class effectively applies given spec to each class method. Method-level @OpenAPIs are merged into class specs, with the former having precedence:

@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 can't unwrap generic types like Promise or Array: see e.g. here for discussion. As a workaround you can use the @ResponseSchema decorator to supply the response body schema:

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

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

@ResponseSchema takes as an argument either a class-validator class or a plain string schema name. You can also supply an optional secondary options argument:

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

contentType and statusCode default to routing-controller's @ContentType and @HttpCode values. To specify a response schema of an array, set options.isArray as true. You can also annotate a single handler with multiple ResponseSchemas to specify responses with different status codes.

Note that when using @ResponseSchema together with @JSONSchema, the outer decorator will overwrite keys of inner decorators. So in the following example, information from @ResponseSchema would be overwritten by @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

Feel free to submit a PR!

Related projects