expressjs+swagger自动生成api文档

文章目录

• ​​一、前置工作​​

• ​​1、下载swaggerUI代码​​
• ​​2、添加swagger官方demo​​
• ​​3、在服务端入口文件追加nodeJS脚本【这里走个过场，不进行这一步也可以】​​

• ​​二、自定义接口​​

• ​​1、编写接口描述文件swagger.json​​
• ​​2、使用swagger.json替换官方demo​​

• ​​三、脚本生成swagger.json​​

• ​​1、安装`swagger`插件​​
• ​​2、按照规则写注释​​
• ​​3、编写nodejs代码​​

一、前置工作

1、下载swaggerUI代码

git clone https://github.com/swagger-api/swagger-ui.git      

2、添加swagger官方demo

1、在服务端目录下新建public目录；

2、将swagger目录dist下文件尽数拷贝到public目录下。

3、在服务端入口文件追加nodeJS脚本【这里走个过场，不进行这一步也可以】

app.use('/doc', express.static('public'));      

通过浏览器访问【http://localhost:4200/doc/】即可以访问到swagger官方的API demo UI。

二、自定义接口

1、编写接口描述文件swagger.json

描述文件编写规则见：

​​

​​

​​​​

使用swagger edit在线编辑器编辑：

​​

​​

​​​​

这部分可以通过yaml语法编辑，完成后选择保存为json文件swagger.json.

2、使用swagger.json替换官方demo

1、将编写完成swagger.json放入public目录；

2、打开public/index.html，将其中的【url: “…”】更换为【url: “swagger.json”】；

3、重新启动项目，然后打开浏览器即可看到与你配置的json相符合的页面：

三、脚本生成swagger.json

1、安装​

​swagger​

​插件

yarn add express-swagger-generator
# or
npm i express-swagger-generator
# or
cnpm i express-swagger-generator      

2、按照规则写注释

详见：https://www.npmjs.com/package/express-swagger-generator

3、编写nodejs代码

const expressSwagger = require('express-swagger-generator')(this.app);
const options = {
  swaggerDefinition: {
    info: {
      description: '吴迪测试',
      title: 'Swagger - 吴迪分享',
      version: '1.0.0',
    },
    host: 'localhost:4200',
    basePath: '/doc',
    produces: [
      "application/json",
      "application/xml"
    ],
    schemes: ['http', 'https'],
    securityDefinitions: {
      JWT: {
        type: 'apiKey',
        in: 'header',
        name: 'Authorization',
        description: "",
      }
    }
  },
  route: {
    url: '/swagger',
    docs: '/swagger.json' //swagger文件 api
  },
  basedir: __dirname, //app absolute path
  files: ['./app/routes/**/*.ts'] //Path to the API handle folder
};
expressSwagger(options);      

这样我们就可以通过http://localhost:4200/swagger进行访问了

【上面定义的doc那个就可以删除掉了】