koa-swagger-decorator
using decorator to auto generate swagger json docs
Installation
npm install koa-swagger-decorator
Introduction
Koa Swagger Decorator
using decorator to auto generate swagger json docs add support validation for swagger definitions
based on Swagger OpenAPI Specification 2.0
support both javascript (babel required) and typescript
Example
// 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
Requirements
- Koa2
- koa-router
- babel support for decorator (or using typescript)
// add [transform-decorators-legacy] to .babelrc
Detail
for more detail please take a look at the example koa server
first wrapper the koa-router object
// router.js const router = // extends from koa-router // swagger docs avaliable at http://localhost:3000/api/swagger-htmlrouter// 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 Classrouter
using decorator to make api definition
// test.js const testTag = 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 @ @ @testTag @ static async { const users = await User ctxbody = users } @ @ @testTag @ static async { const id = ctxvalidatedParams const user = await User ctxbody = user } @ @testTag @ static async { // const body = ctx.request.body; const body = ctxvalidatedBody ctxbody = result: body } static async { ctxbody = result: 'success' }
using decorator to make api body
; ; ;
avaliable annotations
- tags
- query
- path
- body
- formData
- middlewares
- summary
- description
- responses
- deprecated
class annotations
- tagsAll
- responsesAll
- middlewaresAll
- deprecatedAll
- queryAll
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])summary // @summary('api summary')description // @description('api description')responses// @responses({ 200: { description: 'success'}, 400: { description: 'error'}})// responses is optionaldeprecated // @deprecated@@deprecatedAll@ // add middlewares [log1, log2] to all routers in this class@ // can be merged with @query...
validation
support validation type: string, number, boolean, object, array.
properties
in {type: 'object'}
and items
in {type: 'array'}
can alse be validated.
other types eg. integer
will not be validated, and will return the raw value.
by default, validation is activated and you can call ctx.validatedQuery[Body|Params] to access the validated value.
to turn off validation:
router
runing the project and it will generate docs through swagger ui
License
© MIT