Express+Swagger+Yapi

目录

参考文档：

一、解决的主要问题：

二、开始实操！-Swagger部分

注意点

1.安装

 2.在app.js中加入以下代码

3. 在接口上写注释

POST

GET

4.添加api-docs文件夹

5.启动项目

三、开始实操！-Yapi部分

6.MongoDB安装：

7.yapi搭建参考：

8.导入swagger.json

 四、后记

---

三、开始实操！-Yapi部分

5.MongoDB安装：

6.yapi搭建参考：

7.导入swagger.json

 四、后记

---

参考文档：

Swagger and NodeJS

Swagger Editor

GitHub - YMFE/yapi: YApi 是一个可本地部署的、打通前后端及QA的、可视化的接口管理平台

windows环境下局域网搭建Yapi接口管理系统 - 天空之城-意犹未尽 - 博客园

6.MongoDB4.0在Windows环境的下载、安装、配置 - 晨光曦微 - 博客园

一、解决的主要问题：

①post请求的参数是放在请求体里面并且有默认值，避免多次手动输入（查阅的很多文档都是跟在请求路径上）；

② 解决报错：Could not resolve pointer: /definitions/login does not exist。（查阅的文档大多数是针对java+swagger出现此问题的解决方案，对于Nodejs并没有找到）

这里不用下图A的方式，采用下图B的方式。

图A	图B

---

二、开始实操！-Swagger部分

注意点

各种空格

1.安装

npm install swagger-jsdoc@1.3.0 --save

 2.在app.js中加入以下代码

注意按照自己的需求修改部分值

var swaggerJSDoc = require('swagger-jsdoc');

// swagger definition
var swaggerDefinition = {
  info: {
    title: 'Node Swagger API',
    version: '1.0.0',
    description: 'Demonstrating how to describe a RESTful API with Swagger',
  },
  host: 'localhost:8000',
  basePath: '/',
};

// options for the swagger docs
var options = {
  // import swaggerDefinitions
  swaggerDefinition: swaggerDefinition,
  // path to the API docs
  apis: ['./routes/*.js'], //扫描routes文件夹下面的所有js文件
};

// initialize swagger-jsdoc
var swaggerSpec = swaggerJSDoc(options);

// serve swagger
app.get('/swagger.json', function(req, res) {
  res.setHeader('Content-Type', 'application/json');
  res.send(swaggerSpec);
});

3. 在接口上写注释

POST

 /**
 * @swagger
 * /system/login:
 *   post:
 *     tags:
 *       - sys
 *     summary: 登录接口
 *     description:
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: userInfo
 *         description:  object
 *         in: body
 *         required: true
 *         schema:
 *           type: object
 *           properties:
 *             userName:
 *               type: string
 *               example: "test"
 *             password:
 *               type: string
 *               example: "testpassword"
 *     responses:
 *       200:
 *         description: 成功
 */

GET

 /**
 * @swagger
 * /system/logout:
 *   get:
 *     tags:
 *       - sys
 *     summary: 退出登录接口
 *     description:
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: userName
 *         description: 示例 小明
 *         in: query
 *         required: true
 *         type: string
 *     responses:
 *       200:
 *         description: 成功
 */

4.添加api-docs文件夹

在public文件夹下创建api-docs文件夹;

将https://github.com/swagger-api/swagger-ui中的dist文件夹下的内容全部放入api-docs;

将public/api-docs/index.html文件中的

url : "http://petstore.swagger.io/v2/swagger.json";

改为

url: "http://localhost:8000/swagger.json",

 

 

5.启动项目

访问http://localhost:8000/api-docs/ 

三、开始实操！-Yapi部分

6.MongoDB安装：

参考 ：6.MongoDB4.0在Windows环境的下载、安装、配置 - 晨光曦微 - 博客园

7.yapi搭建参考：

参考：windows环境下局域网搭建Yapi接口管理系统 - 天空之城-意犹未尽 - 博客园

8.导入swagger.json

在下列框中输入 http://localhost:8000/swagger.json

 四、后记

欢迎交流哈~Express搭建的后续补充