[Registro 5] Vue + node + koa2 + mysql + nginx + redis, desarrollo de pila completa de pequeños programas y proyectos del sistema de gestión del administrador: use swagger para generar automáticamente documentos de interfaz

Debido a que estamos acoplando documentos de interfaz en diferentes lugares, es muy necesario tener documentos acoplados. Después de la comparación, elegí swagger, pero hay muchas trampas (detalles) en el nodo usando swagger. Me tomó dos días mostrar los documentos, especialmente La parte de comentario debe escribirse estrictamente de acuerdo con el formato.
Elijo swagger-jsdoc y koa2-swagger-ui para implementar.
Primero, iniciemos otro archivo swagger.js en la carpeta de rutas. ¿Por qué está debajo del archivo de rutas? Porque cuando muestra el documento a otros, abre una URL como 127.0.0.1:300/swaggger, por lo que es equivalente a una de las rutas del nodo.

Descargar dependencia

npm instalar swagger-jsdoc koa2-swagger-ui

o

hilo añadir swagger-jsdoc koa2-swagger-ui

versión

Documento de configuración

//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

Importar enrutamiento en el archivo app.js

//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
    }
  })
)

En este momento, la página se ve así:

Notas de interfaz

Si desea que información como la ruta y los parámetros de la interfaz aparezcan en la página 127.0.0.1:300/swagger, debe negociar las anotaciones en la interfaz;
las anotaciones de swagger comienzan con @swagger para facilitar la identificación de swagger: la interfaz de administrador es la siguiente.

//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

Se publicó un documento de interfaz relativamente completo. Lo siguiente también aparecerá en la página:

De esta manera, puede generar su propio documento de interfaz en la página. La siguiente parte presentará las operaciones que debe realizar el front-end para cargar imágenes y mostrar el servidor de imágenes.

Anterior: Permisos de interfaz de controles de token
Siguiente: Carga y descarga de imágenes del servidor