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

Posted 2023-03-30 wiliam_new

先看效果图：

 

 

 

实现步骤：

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: \'请求成功\',
  )
)

 

自律使我自由