routing-controllers-to-openapi

routing-controllers项目构建时生成 openapi v3 schema。
通过TS文件生成AST语法树，分析AST语法树生成openapiv3数据。进而导入到postman、swagger 等平台进行数据展示。

使用

1. 安装依赖

1yarn add routing-controllers-to-openapi --dev

2. 新增script命令

1"scripts": {
2  "gen-openapi": "gen-openapi",
3}

3. 生成openapi数据

1yarn gen-openapi

案例

• Controller案例代码

1import { HeaderParam, JsonController, BodyParam, Post } from 'routing-controllers';
2export interface Response {
3  // code返回码
4  code: number;
5  // 返回信息
6  message: string;
7}
8
9/**
10 * 测试案例controller
11 *
12 * @export
13 * @class TestController
14 */
15@JsonController('/example')
16export default class ExampleController {
17  /**
18   * do something
19   *
20   * @param {string} orgcode 租户号
21   * @param {string} name 姓名
22   * @param {number} age 年龄
23   * @returns {Promise<Response>}
24   * @memberof ExampleController
25   */
26  @Post('/test')
27  async getTest(
28    @HeaderParam('orgcode') orgcode: string,
29    @BodyParam('name') name: string,
30    @BodyParam('age') age: number,
31  ): Promise<Response> {
32    return {
33      code: 0,
34      message: 'success'
35    }
36  }
37}

• generate openapi schema

1{
2    "openapi": "3.0.3",
3    "info": {
4        "title": "routing-coontrollers-to-openapi-test",
5        "description": "Buildtime OpenAPI v3 spec generation for routing-controllers",
6        "version": "1.0.0"
7    },
8    "tags": [
9        {
10            "name": "ExampleController",
11            "description": "测试案例controller"
12        }
13    ],
14    "paths": {
15        "/example/test": {
16            "post": {
17                "tags": [
18                    "ExampleController"
19                ],
20                "summary": "do something",
21                "description": "ExampleController.getTest 测试案例controller ",
22                "operationId": "ExampleController.post.getTest.rhBCjZZSMY",
23                "responses": {
24                    "200": {
25                        "description": "",
26                        "content": {
27                            "application/json": {
28                                "schema": {
29                                    "type": "object",
30                                    "properties": {
31                                        "code": {
32                                            "type": "number",
33                                            "description": "接口返回code码字段"
34                                        },
35                                        "data": {
36                                            "type": "object",
37                                            "properties": {
38                                                "code": {
39                                                    "type": "number",
40                                                    "description": "code返回码"
41                                                },
42                                                "message": {
43                                                    "type": "string",
44                                                    "description": "返回信息"
45                                                }
46                                            },
47                                            "required": [
48                                                "code",
49                                                "message"
50                                            ],
51                                            "additionalProperties": false
52                                        },
53                                        "msg": {
54                                            "type": "string",
55                                            "description": "接口返回信息字段"
56                                        }
57                                    },
58                                    "required": [
59                                        "code",
60                                        "data"
61                                    ]
62                                }
63                            }
64                        }
65                    }
66                },
67                "parameters": [
68                    {
69                        "name": "orgcode",
70                        "in": "header",
71                        "description": "租户号 (@HeaderParam, 类型：string)",
72                        "required": true,
73                        "schema": {
74                            "type": "string"
75                        }
76                    }
77                ],
78                "requestBody": {
79                    "description": "",
80                    "content": {
81                        "application/json": {
82                            "schema": {
83                                "type": "object",
84                                "properties": {
85                                    "name": {
86                                        "type": "string",
87                                        "description": "@BodyParam：姓名"
88                                    },
89                                    "age": {
90                                        "type": "number",
91                                        "description": "@BodyParam：年龄"
92                                    }
93                                },
94                                "required": [
95                                    "name",
96                                    "age"
97                                ]
98                            }
99                        }
100                    }
101                }
102            }
103        }
104    },
105    "components": {
106        "schemas": {}
107    }
108}

Config 配置

项目根目录下创建yundoc.config.js文件

1// yundoc.config.js
2const path = require('path');
3module.exports = {
4  routePrefix: '/api', // routing-controllers路由前缀
5  controllers: [path.join(process.cwd(), "./src/controller/*")],
6  filterFiles: [],
7  requiredType: 'typescript', // typescript | routing-controllers
8  servers: [
9    {
10      url: 'http://127.0.0.1:3000',
11      description: '开发环境域名前缀',
12    }
13  ],
14  // 自定义统一 response 返回结构（可选）
15  responseSchema: {
16    type: 'object',
17    properties: {
18      code: {
19        type: "number",
20        description: "接口返回code码字段",
21      },
22      // data配置必填，格式固定请不要更改
23      data: {
24        $ref: "#Response",
25      },
26      msg: {
27        type: "string",
28        description: "接口返回信息字段",
29      }
30    },
31    required: [
32      "code",
33      "data",
34    ]
35  }
36}

参数说明

字段	类型	必填	说明
routePrefix	string	否	路由前缀，跟routing-controllers保持一致
controllers	string|string[]	否	需要解析的controller文件或需要解析的controller文件夹，默认：/src/controller/*，可根据文件名匹配，例如: /src/**/*Controller.ts，备注： 必须是绝对路径
requiredType	typescript | routing-controllers	否	controller参数必填模式，默认使用typescript
filterFiles	string[]	否	过滤解析的npm包或者ts文件
outfile	string	否	openapi数据存放文件，备注：必须是绝对路径
servers	{url：string,description?:string}[]	否	api根路由与描述
responseSchema	ResponseSchemaObject	否	返回数据包裹层数据格式，由于大部分BFF使用了内置的返回包裹，在controller级别无法解析，因此开发给使用方进行自定义。

responseSchema 参数说明

responseSchema严格遵循JsonSchema数据格式

字段	类型	必填	说明
type	string	是	值为object，固定值不要更改（描述当前schema数据类型）
properties	{[prop:string]: {type?:string;$ref?:string;description?:string}}	否	当前对象的属性描述信息。
required	string[]	否	描述当前object的必填字段，若无必填字段则不需要此参数

• properties 字段描述

字段	类型	必填	说明
type	string	是	此处type只需要填写简单类型，例如：string,number,boolean
$ref	string	是	此处为固定值：#Response, 不要更改
description	string	否	当前字段描述信息

备注： properties 中 $ref 和 type必须有一项为真。

 routing-controllers 支持项

支持的类型解析列表

example 案例

1git clone https://github.com/yunke-yunfly/routing-controllers-to-openapi.git
2cd routing-controllers-to-openapi
3yarn install
4yarn build
5yarn example

贡献

我们非常欢迎您的贡献，您可以通过以下方式与我们共建。

• 提交GitHub 问题以报告错误或提出问题。
• 提出拉取请求以改进我们的代码。
• 贡献指南。