koa使用swagger装饰路由比起手动用postman调试，在线swagger调试要简单方便的多。所以就想着写一个完整

前言

一开始看到开源的 koa-swagger-decorator 这个项目的时候眼前一亮，比起手动用postman调试，在线swagger调试要简单方便的多。所以就想着写一个完整一点的项目供自己和大家学习。

先上自己的代码：koa-swagger

介绍

这是一个基于 Koa2 添加Swagger的脚手架

包括对应的sequelize对数据库的直接操作

以及jwt 认证

关于swagger

这里采用的是koa-swagger-decorator

特点是开箱即用，支持在线调试，RESTful API接口文档清晰了然

但是同时入侵性很强，二次开发非常不方便，schema可复用性不高，只适合用于小型项目中。(但是如果你是一个初学者，那么就更适合你了！)

该项目主要是通过为Controller添加装饰器的方式，自动来为外界生成接口文档。举个例子：

在这个getTodoList方法上面，通过引入的装饰器，分别为其描述swagger的路由地址，描述，请求参数等

// list.js

import ListModel from 'models/list'
import { request, summary, description, query, path, body, tags } from 'koa-swagger-decorator'

const tag = tags(['list'])


const getListSchema = {
  keyword: { type: 'string', required: true },
  status: { type: 'number', required: true }
}
export default class ListController {
  @request('get', '/list/list')
  @summary('返回一个列表')
  @description('example of api')
  @tag
  @query(getListSchema)
  static async getTodoList(ctx) {
    const data = ctx.request.query
    if (data) {
      const todoList = await ListModel.getTodoList(data.keyword, data.status)
      ctx.body = {
        code: 1,
        bean: {
          totalCount: todoList.totalCount,
          list: todoList.items,
        },
        message: '成功'
      }
    } else {
      ctx.body = {
        code: -1,
        message: '参数错误'
      }
    }
  }

}

以及对应生成的接口为：

如何使用

关于sequelize和数据库

这里使用的是关系型数据库的ORM sequelize

支持多种数据库，请先在 config.js中修改对应的数据库连接设置，例如 db_type：mysql mariadb sqlite postgres mssql

我这里使用的是postgres，如果修改了数据库类型之后运行对应的 npm install mysql 或 npm install postgres 之类……

在配置好数据库之后将会自动为数据库创建对应的model

开始运行

npm install
npm run dev


然后打开： http://localhost:3000/swagger-html
你就可以看到熟悉亲切的swagger页面了

登录与授权

这里采用的是jwt的方式，必须使用token。同时在app.js里面也声明了 path: [/^/user/login/, /^/user/register/, /^/swagger/, /^/public/]的路由是不受验证(允许匿名请求)

第一步先使用 /public/initData 的接口初始化数据，这时数据库就产生了登录的user和列表list的数据

第二步接下来在注册接口 /user/register 或者登录接口 /user/login 请求返回token

第三步最后将token授权打开Authorize按钮，记得前面携带 Bearer 然后点击Authorize。

最后在授权之后就可以对list列表增删查改了

结语

这是第一次在掘金发表文章，如果有什么不对的地方欢迎大家指出并探讨。如果大家有兴趣的话可以继续去看源码