node接入swagger

前言

之前的node项目中，所有的开发文档都是手动由后天开发者编写，之后交给前端。当后续接口变动，或者参数调整之后，文档更新不及时，而且混乱。需要进行很多无效的沟通。我们最终选择swagger，swagger支持和测试就扣使用都非常方便，在java中表现也非常优异。

安装

安装：npm install express-swagger-generator

配置

从启动项 index.js 中添加引用。当然你的项目也可能是app.js等等。

if (AppConfig.env === 'dev') {
    require("./setting/swagger-setting")(app);
    app.listen(3000, () => console.log("swagger started!! port: 3000"));
}

swagger-setting 说明

我不想再index.js中有太强的入侵性，就将配置swagger的代码提出到一个单独类中。

const Generator = require('express-swagger-generator');

const Options = {
    swaggerDefinition: {
        info: {
            description: '项目介绍',
            title: 'Swagger API',
            version: '1.0.0'
        },
        host: 'localhost:3000',//ip和端口
        basePath: '/',
        produces: ['application/json', 'application/xml'],
        schemes: ['http', 'https'],
        securityDefinitions: {
            JWT: {
                type: 'apiKey',
                in: 'header',
                name: 'Authorization',
                description: ''
            }
        }
    },
    route: {
        url: '/swagger',//对应模块的接口，不同服务请指定不同接口
        docs: '/swagger.json'
    },
    basedir: __dirname,
    files: ["../router/*.js","../service/*.js",]//可指定多个目录，只有指定的文件夹下的注释才会生成文档
}

module.exports = function setSwagger(app) {
    const expressSwagger = Generator(app);
    expressSwagger(Options);
}

注释说明

我们再开发中就需要标准我们的注释规范了。对于需要提供出来的接口，只要按照下面的界面展示就好了

    /**
     * 项目用户个人信息                                               (必填)
     * @route POST /user/info                                      （必填：对应接口）
     * @group v1 - 普通用户查询                                      （群组，方便按照用能或模块区分接口）
     * @param {int} tyep.query.required - 类型：1 A、 2 B           （参数）
     * @returns {object} suc - 成功之后的结果                        （返回正确结构）
     * @returns {Error}  failed - 失败之后的结果                     （返回错误结构）
     */

注：

".query.required" 代表必填
"-" 之后是解释说明
生效的注释必须是 module.exports 暴露出来的，否则不生效

查看网址

http://localHost:3000/swagger

参考文档

一点浩然气，千里快哉风