科阿-斯瓦格-代号
使用装饰器自动生成 swagger json 文件
安装
npm install koa-swagger-decorator
贡献指南
请参考 捐款 在创建您的公关或问题之前.
导言
Koa Swagger 装饰器
使用装饰器自动生成 swagger json docs 为 swagger 定义添加支持验证
支持 javascript (需要的babel) 和打字符
示例
// using commonds below to start and test the example server
git clone https://github.com/Cody2333/koa-swagger-decorator.git
cd koa-swagger-decorator
npm install
npm run start
finally open:
http://localhost:3000/api/swagger-html
所需资源
- 科亚2
- 旋转道
- 装饰器的 bail 支持( 或使用打字符)
// add [transform-decorators-legacy] to .babelrc if using js
npm install --save-dev babel-plugin-transform-decorators-legacy
{
"presets": [
["env", {"targets": {"node": "current"}}]
],
"plugins": ["transform-decorators-legacy"]
}
细节
详情请看 例 koa 服务器
将 koa 路由对象先包裹
// router.js
import Router from 'koa-router'
import Test from './test'
import { SwaggerRouter } from 'koa-swagger-decorator'
const router = new SwaggerRouter([KoaRouterOpts],[SwaggerOpts]) // extends from koa-router
// swagger docs avaliable at http://localhost:3000/api/swagger-html
router.swagger({
title: 'Example Server',
description: 'API DOC',
version: '1.0.0',
// [optional] default is root path.
// if you are using koa-swagger-decorator within nested router, using this param to let swagger know your current router point
prefix: '/api',
// [optional] default is /swagger-html
swaggerHtmlEndpoint: '/swagger-html',
// [optional] default is /swagger-json
swaggerJsonEndpoint: '/swagger-json',
// [optional] additional options for building swagger doc
// eg. add api_key as shown below
swaggerOptions: {
securityDefinitions: {
api_key: {
type: 'apiKey',
in: 'header',
name: 'api_key',
},
},
},
// [optional] additional configuration for config how to show swagger view
swaggerConfiguration: {
display: {
defaultModelsExpandDepth: 4, // The default expansion depth for models (set to -1 completely hide the models).
defaultModelExpandDepth: 3, // The default expansion depth for the model on the model-example section.
docExpansion: 'list', // Controls the default expansion setting for the operations and tags.
defaultModelRendering: 'model' // Controls how the model is shown when the API is first rendered.
}
}
})
// map all static methods at Test class for router
// router.map(Test);
// mapDir will scan the input dir, and automatically call router.map to all Router Class
router.mapDir(_path.resolve(__dirname), {
// default: true. To recursively scan the dir to make router. If false, will not scan subroutes dir
// recursive: true,
// default: true, if true, you can call ctx.validatedBody[Query|Params] to get validated data.
// doValidation: true,
// default: [], paths to ignore while looking for decorators
// ignore: ["**.spec.ts"],
})
使用装饰器制作 api 定义
// test.js
import User from 'models/user'
import { request, summary, query, path, body, tags } from 'koa-swagger-decorator'
const testTag = tags(['test'])
const userSchema = {
name: { type: 'string', required: true },
gender: { type: 'string', required: false, example: 'male' },
groups: {
type: 'array',
required: true,
items: { type: 'string', example: 'group1' }, // item's type will also be validated
},
}
export default class Test {
@request('get', '/users')
@summary('get user list')
@security([{ api_key: [] }])
@testTag
@query({
type: { type: 'number', required: true, default: 1, description: 'type' },
})
static async getUsers(ctx) {
const users = await User.findAll()
ctx.body = { users }
}
@request('get', '/users/{id}')
@summary('get user info by id')
@security([{ api_key: [] }])
@testTag
@path({
id: { type: 'number', required: true, default: 1, description: 'id' },
})
static async getUser(ctx) {
const { id } = ctx.validatedParams
const user = await User.findById(id)
ctx.body = { user }
}
@request('post', '/users')
@testTag
@body(userSchema)
static async postUser(ctx) {
// const body = ctx.request.body;
const body = ctx.validatedBody
ctx.body = { result: body }
}
static async temp(ctx) {
ctx.body = { result: 'success' }
}
}
使用装饰来制作 api 体
import Router from 'koa-router';
import { request, summary, query, path, body, tags, swaggerClass, swaggerProperty } from 'koa-swagger-decorator'
@swaggerClass()
export class subObject {
@swaggerProperty({ type: "string", required: true }) Email: string = "";
@swaggerProperty({ type: "string", required: true }) NickName: string = "";
@swaggerProperty({ type: "string", required: true }) Password: string = "";
};
@swaggerClass()
export class userInfo {
@swaggerProperty({ type: "string", required: true }) Email: string = "";
@swaggerProperty({ type: "string", required: true }) NickName: string = "";
@swaggerProperty({ type: "string", required: true }) Password: string = "";
@swaggerProperty({type:"object",properties:(subObject as any).swaggerDocument}) UserInfo:subObject;
};
export default class Test {
@request('POST', '/user/Register')
@summary('register user')
@description('example of api')
@body((userInfo as any).swaggerDocument)
static async Register(ctx: Router.IRouterContext) {
var params = (ctx as any).validatedBody as userInfo;
console.log(params);
}
}
可验证说明
- 标记
- 查询
- 路径
- 机构
- 窗体数据
- 中间软件
- 警卫
- 目录
- 说明
- 答复
- 已贬值
类说明
- 标记全部
- 回复
- 中间软件
- 全部安全
- 全部贬值
- 全部查询
request // @request('POST', '/users')
tags // @tags(['example'])
query // @query({limit: {type: 'number', required: true, default: 10, description: 'desc'}})
path // @path({limit: {type: 'number', required: true, default: 10, description: 'desc'}})
body // @body({groups: {type: 'array', required: true, items: { type: 'string', example: 'group1' }}})
formData // @formData({file: {type: 'file', required: true, description: 'file content'}})
middlewares
// support koa middlewares.
// eg. @middlewares([func1,func2])
security
// define authentication method, key must be same as one of methods defined in swaggerOptions.securityDefinitions
// @security([{ api_key: [] }])
summary // @summary('api summary')
description // @description('api description')
responses
// @responses({ 200: { description: 'success'}, 400: { description: 'error'}})
// responses is optional
deprecated // @deprecated
@tagsAll(['A', 'B'])
@deprecatedAll
@securityAll([{ api_key: [] }])
@middlewaresAll([log1, log2]) // add middlewares [log1, log2] to all routers in this class
@queryAll({ limit: { type: 'number', default: 444, required: true } }) // can be merged with @query
export default class SampleRouter {
...
}
验证
支持验证类型 : string, number, boolean, object, array.
properties 内 {type: 'object'} 财务报告和审定财务报表 items 内 {type: 'array'} 还可以验证.
其他类型,例如:. integer 将不会被验证,并将返回原始值.
默认情况下,验证被激活,您可以调用 ctx.validatedQuery [Body|Params] 访问已验证值.
以关闭验证 :
router.mapDir(_path.resolve(__dirname), {
// default: true, if true, you can call ctx.validatedBody[Query|Params] to get validated data.
doValidation: false,
})
运行此工程, 它会通过 swagger ui 生成文件
许可证
麻省理工学院