如何在nodejs中使用swagger

在工作中和后台javaer进行接口调试的时候使用的是swagger,非常的方便。nodejs中有什么好用的api工具呢？网上查找了一下，swagger同样适用于nodejs,记录一下在nodejs中使用swagger的过程。

1、 安装依赖

npm install swagger-ui-express swagger-jsdoc -S

2、创建swagger中间件

• 在utils/swagger文件夹中创建index.js
• 配置swagger-jsdoc中的options
• 注意修改swagger收集注释的路由

const path = require('path')
const express = require('express')
const swaggerUI = require('swagger-ui-express')
const swaggerDoc = require('swagger-jsdoc')
//配置swagger-jsdoc
  const options = {
    definition: {
      openapi: '3.0.0',
      info: {
        title: 'api',
        version: '1.0.0',
        description: `小程序+管理后台共用接口api`
      }
    },
    // 去哪个路由下收集 swagger 注释
    apis: [path.join(__dirname,'../../routes/*.js')]
  }

  var swaggerJson = function (req, res) {
    res.setHeader('Content-Type', 'application/json');
    res.send(swaggerSpec);
  }
  const swaggerSpec = swaggerDoc(options)
  
  var swaggerInstall = function(app) {
    if (!app){
      app = express()
    }
    // 开放相关接口，
    app.get('/swagger.json', swaggerJson);
    // 使用 swaggerSpec 生成 swagger 文档页面，并开放在指定路由
    app.use('/swagger', swaggerUI.serve, swaggerUI.setup(swaggerSpec));
  }
  module.exports = swaggerInstall 

3、在app.js中引用swagger中间件的swaggerInstall方法

// 使用swagger API 文档
var swaggerInstall = require('./utils/swagger')
swaggerInstall(app)

4、swagger 在js 中的注释如下所示，可在配置的路径下任意js地方注释，swagger-jsdoc会遍历查找

/**,
 * @swagger
 * /api/addExam:
 *    post:
 *      tags:
 *      - 测试
 *      summary: 提交考试答案
 *      produces:
 *      - application/json
 *      parameters:
 *      - name: name
 *        in: query
 *        description: 姓名
 *        required: false
 *        type: integer
 *        maximum:
 *        minimum: 1
 *        format:
 *      - name: phone
 *        in: query
 *        description: 电话
 *        required: false
 *        type: integer
 *        maximum:
 *        minimum: 1
 *        format:
 *      responses:
 *        200:
 *          description: successful operation
 *          schema:
 *            ref: #/definitions/Order
 *        400:
 *          description: Invalid ID supplied
 *        404:
 *          description: Order not found
 * */

5、访问api

• npm start 运行项目
• 输入 http://localhost:3000/swagger 访问本地api