Nodejs中使用swagger

在Node.js后端服务中配置swagger：

1. 安装依赖

npm i swagger-jsdoc --save
npm i swagger-ui-express --save

2. 创建swagger入口文件

const path = require('path')
const express = require('express')
const swaggerUI = require('swagger-ui-express')
const swaggerDoc = require('swagger-jsdoc')

const paths = require('./routes/index')

// swaggger-jsdoc配置
const options = {
    definition: {
        openapi: '3.1.0',
        info: {
            title: 'service swagger page',
            version: 'V0.0.1',
            decription: 'This is the service swagger page',
            contact: {
                name: '服务swagger地址',
                url: 'https://xxx.com',
            },
        },
        // 可以访问的地址
        servers: [
            {
              url: 'https://xxx-dev.com',
              description: 'Development server',
            },
            {
                url: 'https://xxx-test.com',
                description: 'Test server',
            },
            {
                url: 'https://xxx-prod.com/',
                description: 'Prod server',
            }
        ],
        // swagger文档路径,路由键值对
        paths: paths
    },
    // 去哪个路由下收集swagger
    apis: [path.join(__dirname, '../router/*.js')]
}

let swaggerSpec = swaggerDoc(options)

let swaggerJSON = function(req, res) {
    res.setHeader('Content-Type', 'application/json')
    res.send(swaggerSpec)
}

let swaggerInstall = function(app) {
    if(!app) {
        app = express()
    }
    // 开放接口
    app.get('/service-swagger/index.json', swaggerJSON)
    // 使用swaggerSpec生产swagger文档页面，并开放在指定路由
    app.use('/service-swagger/index', swaggerUI.serve, swaggerUI.setup(swaggerSpec))
}

module.exports = swaggerInstall

从上面的代码来看，我们需要其中一个变量：paths。它是添加swagger路由的文件，我们在下一步中介绍

3. 创建路由文件

const Utils = require('../utils/index')

/**
 * 路由埋点接口
 */
const paths = {
    "/sergice/get": {
        get: {
            tags: ['service controller'], // 接口分类
            summary: 'get请求', // 接口备注
            description: 'get请求', // 接口描述
            consumes: ['application/json' ], // 接口接收参数方式
            parameters: [ // 接口查询参数，此处只列举一个，还可以增加其它的
                {
                    name: "name",
                    in: "query",
                    type: "string",
                    required: false
                }
            ],
            responses: Utils.response
        }
    },
    "/service/post": {
        put: {
            tags: ['service controller'], // 接口分类
            summary: 'post请求', // 接口备注
            description: 'post请求', // 接口描述
            consumes: ['application/json' ], // 接口接收参数方式
            requestBody: {
                required: true, // 是否必传
                content: {
                    'application/json': {
                        // 参数备注
                        schema: {
                            type: Object,
                            properties: { // 接口查询参数，此处只列举一个，还可以增加其它的
                                name: {
                                    type: string,
                                    description: 'name'
                                }
                            }
                        },
                        //请求参数样例
                        example: {
                            "name": "修改"
                        },
                    }
                }
            },
            parameters: [
                {
                    name: "client_id"
                }
            ],
            responses: Utils.response
        }
    },
module.exports = paths

上述我们列举了post和get请求的示例。其它请求方式的书写可以参考官方网站

4. 入口文件中添加

// swagger
const swaggerInstall = require('../swagger/index')
swaggerInstall(app)

这样一来，只要服务启动该，就可以访问swagger页面。访问swagger的地址就是index.js文件中定义的：域名 + /service-swagger/index