[Record 5] Vue+node+koa2+mysql+nginx+redis, full-stack development of small programs and administrator management system projects-use swagger to automatically generate interface documents

Because we are docking interface documents in different places, it is very necessary to have docking documents. After comparison, I chose swagger, but there are many pitfalls (details) in node using swagger. It took me two days to show the documents, especially The comment part needs to be written in strict accordance with the format.
I choose swagger-jsdoc and koa2-swagger-ui to implement.
First of all, let's start another file swagger.js in the routes folder. Why is it under the routes file? Because when you show the document to others, you open a URL like 127.0.0.1:300/swaggger, so it is equivalent to one of node's routes.

Download dependency

npm install swagger-jsdoc koa2-swagger-ui

yarn add swagger-jsdoc koa2-swagger-ui

version

Insert picture description here

Configuration document

//swagger.js
const router = require('koa-router')()
const swaggerJSDoc = require('swagger-jsdoc')
const swaggerDefinition = {
    
    
  info: {
    
    
    title: '你的文档标题',
    version: '1.0.0',
    description: '你的文档说明'
  },
  securityDefinitions: {
    
    
    ApiKeyAuth: {
    
    
      type: 'apiKey', // 类型
      in: 'header', // 位置
      name: 'token' // 参数
    }
  },
  host: '127.0.0.1:300',//需要跟你node服务器地址一样
  basePath: '/' // Base path (optional)
};
const options = {
    
    
  swaggerDefinition,
  apis: ['./routes/*.js'] // 写有注解的router的存放地址
};
const swaggerSpec = swaggerJSDoc(options)
// 通过路由获取生成的注解文件
router.get('/swagger.json', async function (ctx) {
    
    
  ctx.set('Content-Type', 'application/json')
  ctx.body = swaggerSpec
})
module.exports = router

Import routing in app.js file

//app.js
const koaSwagger = require('koa2-swagger-ui')

//swagger配置
app.use(//注意这里需要看koa2-swagger-ui的版本 不然会报koaSwagger不是一个函数等错误
  koaSwagger({
    
    
    routePrefix: '/swagger', // host at /swagger instead of default /docs
    swaggerOptions: {
    
    
      url: '/swagger.json' // example path to json
    }
  })
)

At this time the page looks like this:

Insert picture description here

Interface notes

If you want information such as the path and parameters of the interface to appear on the 127.0.0.1:300/swagger page, you need to negotiate the annotations at the interface;
the annotations of swagger start with @swagger to facilitate swagger identification: the administrator interface is the chestnut below.

//admin.js
// #region 
// #region可以将注释代码收缩
/**
 * @swagger
 * /admin/userLogin:
 *   post:
 *     summary: 管理员登录
 *     description: 管理员登录
 *     tags:
 *       - 管理员模块
 *     parameters:
 *       - name: name
 *         in: query
 *         required: true
 *         description: 账号
 *         type: string
 *       - name: password
 *         in: query
 *         required: true
 *         description: 密码
 *         type: string
 *     responses:
 *       200:
 *         description: 成功获取
 *         schema:
 *           type: 'object'
 *           properties:
 *             code:
 *               type: 'number'
 *             data:
 *               type: 'object'
 *               description: 返回数据
 *             message:
 *               type: 'string'
 *               description: 消息提示
 */
// #endregion

Such a relatively complete interface document came out. The following will also appear on the page:

Insert picture description here
In this way, you can output your own interface document on the page. The next part will introduce what operations the front-end requests to upload pictures and display picture server need to do.

Previous: Token controls interface permissions
Next: Server image upload and download