routing-controllers-to-openapi
v0.0.7
Published
Buildtime OpenAPI v3 spec generation for routing-controllers.
Downloads
7
Maintainers
Readme
routing-controllers-to-openapi
routing-controllers项目构建时生成 openapi v3 schema。
通过TS文件生成AST语法树
,分析AST语法树生成openapiv3
数据。进而导入到postman
、swagger
等平台进行数据展示。
使用
1. 安装依赖
yarn add routing-controllers-to-openapi --dev
2. 新增script命令
"scripts": {
"gen-openapi": "gen-openapi",
}
3. 生成openapi数据
yarn gen-openapi
案例
- Controller案例代码
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<Response>}
* @memberof ExampleController
*/
@Post('/test')
async getTest(
@HeaderParam('orgcode') orgcode: string,
@BodyParam('name') name: string,
@BodyParam('age') age: number,
): Promise<Response> {
return {
code: 0,
message: 'success'
}
}
}
- generate openapi schema
{
"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": {}
}
}
Config 配置
项目根目录下创建yundoc.config.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保持一致
|
| 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 案例
git clone https://github.com/yunke-yunfly/routing-controllers-to-openapi.git
cd routing-controllers-to-openapi
yarn install
yarn build
yarn example
贡献
我们非常欢迎您的贡献,您可以通过以下方式与我们共建。