Buildtime OpenAPI v3 spec generation for routing-controllers.
npm install routing-controllers-to-openapi
!Test
routing-controllers项目构建时生成 openapi v3 schema。
通过TS文件生成AST语法树，分析AST语法树生成openapiv3数据。进而导入到postman、swagger 等平台进行数据展示。
``js`
yarn add routing-controllers-to-openapi --dev
`js`
"scripts": {
"gen-openapi": "gen-openapi",
}
`js`
yarn gen-openapi
- Controller案例代码
`ts
import { HeaderParam, JsonController, BodyParam, Post } from 'routing-controllers';
export interface Response {
// code返回码
code: number;
// 返回信息
message: string;
}
/**
* 测试案例controller
*
* @export
* @class TestController
*/
@JsonController('/example')
export default class ExampleController {
/**
* do something
*
* @param {string} orgcode 租户号
* @param {string} name 姓名
* @param {number} age 年龄
* @returns {Promise
* @memberof ExampleController
*/
@Post('/test')
async getTest(
@HeaderParam('orgcode') orgcode: string,
@BodyParam('name') name: string,
@BodyParam('age') age: number,
): Promise
return {
code: 0,
message: 'success'
}
}
}
`
- generate openapi schema
`json`
{
"openapi": "3.0.3",
"info": {
"title": "routing-coontrollers-to-openapi-test",
"description": "Buildtime OpenAPI v3 spec generation for routing-controllers",
"version": "1.0.0"
},
"tags": [
{
"name": "ExampleController",
"description": "测试案例controller"
}
],
"paths": {
"/example/test": {
"post": {
"tags": [
"ExampleController"
],
"summary": "do something",
"description": "ExampleController.getTest 测试案例controller ",
"operationId": "ExampleController.post.getTest.rhBCjZZSMY",
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "接口返回code码字段"
},
"data": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "code返回码"
},
"message": {
"type": "string",
"description": "返回信息"
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
},
"msg": {
"type": "string",
"description": "接口返回信息字段"
}
},
"required": [
"code",
"data"
]
}
}
}
}
},
"parameters": [
{
"name": "orgcode",
"in": "header",
"description": "租户号 (@HeaderParam, 类型：string)",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "@BodyParam：姓名"
},
"age": {
"type": "number",
"description": "@BodyParam：年龄"
}
},
"required": [
"name",
"age"
]
}
}
}
}
}
}
},
"components": {
"schemas": {}
}
}
`js`
// yundoc.config.js
const path = require('path');
module.exports = {
routePrefix: '/api', // routing-controllers路由前缀
controllers: [path.join(process.cwd(), "./src/controller/*")],
filterFiles: [],
requiredType: 'typescript', // typescript | routing-controllers
servers: [
{
url: 'http://127.0.0.1:3000',
description: '开发环境域名前缀',
}
],
// 自定义统一 response 返回结构（可选）
responseSchema: {
type: 'object',
properties: {
code: {
type: "number",
description: "接口返回code码字段",
},
// data配置必填，格式固定请不要更改
data: {
$ref: "#Response",
},
msg: {
type: "string",
description: "接口返回信息字段",
}
},
required: [
"code",
"data",
]
}
}
| 字段 | 类型 | 必填 |说明 |
| ------ | ------ |------ |------ |
| routePrefix | string | 否 | 路由前缀，跟routing-controllers保持一致 |string\|string[]
| controllers | | 否 | 需要解析的controller文件或需要解析的controller文件夹，默认：/src/controller/，可根据文件名匹配，例如: /src//Controller.ts，备注： 必须是绝对路径 |typescript \| routing-controllers
| requiredType | | 否 | controller参数必填模式，默认使用typescript |string[]
| filterFiles | | 否 | 过滤解析的npm包或者ts文件 |string
| outfile | | 否 | openapi数据存放文件，备注：必须是绝对路径 |{url：string,description?:string}[]
| servers | | 否 | api根路由与描述 |ResponseSchemaObject
| responseSchema | | 否 | 返回数据包裹层数据格式，由于大部分BFF使用了内置的返回包裹，在controller级别无法解析，因此开发给使用方进行自定义。|
responseSchema严格遵循JsonSchema数据格式
| 字段 | 类型 | 必填 |说明 |
| ------ | ------ |------ |------ |
| type | string | 是 | 值为object，固定值不要更改（描述当前schema数据类型） |{[prop:string]: {type?:string;$ref?:string;description?:string}}
| properties | | 否 | 当前对象的属性描述信息。 |string[]
| required | | 否 | 描述当前object的必填字段，若无必填字段则不需要此参数 |
- properties 字段描述
| 字段 | 类型 | 必填 |说明 |
| ------ | ------ |------ |------ |
| type | string | 是 | 此处type只需要填写简单类型，例如：string,number,boolean |string
| $ref | | 是 | 此处为固定值：#Response, 不要更改 |string
| description | | 否 | 当前字段描述信息 |
> 备注： properties 中 $ref 和 type必须有一项为真。
`js``
git clone https://github.com/yunke-yunfly/routing-controllers-to-openapi.git
cd routing-controllers-to-openapi
yarn install
yarn build
yarn example
我们非常欢迎您的贡献，您可以通过以下方式与我们共建。