node express自动生成swagger(openApi)接口文档

先看效果图：

 

 

 

实现步骤：

1. 安装所需的包

npm install swagger-jsdoc swagger-ui-express

2. 新建文件 swagger.js

// swagger在线网站：https://editor.swagger.io/#

const swaggerJSDoc = require('swagger-jsdoc')
const swaggerUi = require('swagger-ui-express')
const path = require('path')

const swaggerInit = (app, baseUrl) => {
  //options是swaggerJSDoc的配置项
  const options = {
    swagger: '2.0',
    //definition是swagger的配置项
    definition: {
      info: {
        title: 'Node Swagger API',
        version: '1.0.0',
        description: 'Demonstrating how to describe a RESTful API with Swagger',
      },
    },
    // 重点，指定 swagger-jsdoc 去哪个路由下收集 swagger 注释
    apis: [path.join(process.cwd(), '/routes/*.js')],
  }
  const swaggerSpec = swaggerJSDoc(options)

  // 可以访问 xxx/swagger.json 看到生成的swaggerJSDoc
  app.get('/swagger.json', function (req, res) {
    res.setHeader('Content-Type', 'application/json')
    res.send(swaggerSpec)
  })

  // 可以访问 xxx/api-docs 看到生成的swagger接口文档
  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec))
}

module.exports = swaggerInit

3. 在app.js中引入swagger.js文件

const app = express()

//swagger imports
//这里填你的swagger文件所在路径
const swaggerInit = require('./swagger.js')
swaggerInit(app)

4. 写一个swagger格式的接口

const express = require('express')
const router = express.Router()

/**
 * @swagger
 * /api/getPetList:
 *  get:
 *   tags:
 *     - pet
 *   description: Multiple name values can be provided with comma separated strings
 *   parameters:
 *     - name: name
 *       in: query
 *       description: name values that need to be considered for filter
 *       required: false
 *   responses:
 *     '200':
 *       description: successful operation
 *     '400':
 *       description: Invalid name value
 */
router.get('/api/getPetList', (req, res, next) => {
  const { query } = req
  res.send({
    status: 200,
    data:[],
    msg: '请求成功',
  })
})

module.exports = router

 

大功告成！现在你可以通过访问 http://IP:端口/api-docs/ 得到一开始的效果图了。

 

附上其它请求方式的swagger写法：

/**
 * @swagger
 * definitions:
 *   Pet:
 *     properties:
 *       name:
 *         type: string
 *       age:
 *         type: integer
 *       sex:
 *         type: string
 */

/**
 * @swagger
 * /api/petAdd:
 *   post:
 *     tags:
 *       - pet
 *     description: Creates a new pet
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: pet
 *         description: pet object
 *         in: body
 *         required: true
 *         schema:
 *           $ref: '#/definitions/Pet'
 *     responses:
 *       200:
 *         description: Successfully created
 */
router.post('/api/petAdd', (req, res, next) => {
  const { query } = req
  res.send({
    status: 200,
    data: true,
    msg: '请求成功',
  })
})

/**
 * @swagger
 * /api/puppies/{id}:
 *   put:
 *     tags:
 *      - pet
 *     description: Updates a single pet
 *     produces:
 *      - application/json
 *     parameters:
 *      - name: pet
 *        description: Fields for the pet resource
 *        in: body
 *        schema:
 *         type: array
 *         $ref: '#/definitions/Pet'
 *     responses:
 *       200:
 *         description: Successfully updated
 */

router.put('/api/petEdit', (req, res, next) => {
  const { query } = req
  res.send({
    status: 200,
    data: true,
    msg: '请求成功',
  })
})

/**
 * @swagger
 * /api/petDelete:
 *   delete:
 *     tags:
 *       - pet
 *     description: Deletes a single pet
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: id
 *         description: pet's id
 *         in: path
 *         required: true
 *         type: integer
 *     responses:
 *       200:
 *         description: Successfully deleted
 */
router.put('/api/petDelete', (req, res, next) => {
  const { query } = req
  res.send({
    status: 200,
    data: true,
    msg: '请求成功',
  })
})

 

 

当然，如果你觉得这种注释很难写，有更推荐的方案 https://www.npmjs.com/package/express-swagger-generator