OpenAPIv3 document generator for routing-controllers (WIP)
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
build
.gitignore
README.md
helper.ts
index.ts
package.json
tsconfig.json
yarn.lock

README.md

Routing-Controllers-OpenAPI-V3 (WIP)

Auto generate document of OpenAPI v3 Spec format.

Condition & Limitation

  1. the param name be decorated by @QueryParams should always be query
  2. the param name be decorated by @Body should always be body
  3. always use class or inherit type as params type, don't use type operator in action function params or @ResType
  4. every controller should have a base path, which will be output as openapi tag
  5. route path should be a string, regex is not supported now
  6. set emitDecoratorMetadata to true in tsconfig.json

Example

SourceCode:

// Model
class Article {
    title: string;
    author: string;
}

// QueryParams class, note that to make this library work, 
// you should always use class instead of interface.
class ArticleQuery {
    limit: number = 10;	// Default value will be output to document~
    offset: number = 0;
}

@JsonController('/article')	// This is required, and will be output as openapi document tag
export class ArticleController {
    @Inject() articleService: ArticleService
    
    @Description('Fetch Article List')	// @Description to mark description
    @ResType([Article])	// [Article] => Article[], Article => Article
    @Get('/')
    async getArticleList(@QueryParams() query: ArticleQuery): Promise<Article[]> {
        return this.articleService.getArticleList(query)
    }
}

Usage of this library:

import docGenerator from 'routing-controller-openapi-v3'
import { getMetadataArgsStorage } from 'routing-controllers'

docGenerator(getMetadataArgsStorage(), {
  info: {
    title: 'SteamCN-VNext API',
    description: 'API Document for SteamCN-VNext',
    version: '0.7.0'
  },
  servers: [{
    url: 'https://api.example.com/v1',
    description: 'test'
  }]
})

Output:

{
    "openapi": "3.0.0",
    "info": {
        "title": "SteamCN-VNext API",
        "description": "API Document for SteamCN-VNext",
        "version": "0.7.0"
    },
    "servers": [
        {
            "url": "https://api.example.com/v1",
            "description": "test"
        }
    ],
    "paths": {
        "/article": {
            "get": {
                "description": "Fetch Article List",
                "tags": [
                    "article"
                ],
                "parameters": [
                    {
                        "in": "query",
                        "name": "limit",
                        "schema": {
                            "type": "number",
                            "default": 10
                        }
                    },
                    {
                        "in": "query",
                        "name": "offset",
                        "schema": {
                            "type": "number",
                            "default": 0
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/Article"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "tags": [
    	{
    		"name": "article"
		  }
    ],
    "components": {
        "schemas": {
            "Article": {
                "type": "object",
                "properties": {
                    "title": {
                        "type": "string"
                    },
                    "author": {
                        "type": "string"
                    }
                },
                "required": [
                    "title",
                    "author",
                ]
            }
        }
    }
}