Development environment: nodejs + express
Requirements: You need to use swagger to import the interface into YApi, but but but never used it!
First, attach the reference pipe network: https://swagger.io/docs/specification/authentication/ Since
most of the online tutorials are not yet complete, it is hereby compiled (for reference only)
Sample after completion:
1. Introduce the
specific code of swagger into the app.js file as follows
require("./swagger")(app);
2. Create a new swagger folder in the root directory of the project and create a new index.js document to write the basic settings of swagger.
The specific code is as follows:
var path = require("path");
var express = require("express");
var swaggerUi = require("swagger-ui-express");
var swaggerJSDoc = require("swagger-jsdoc");
//author:LianSP
//comment:swagger请求路径：http://localhost:9009/swagger
// 配置 swagger-jsdoc
const options = {
definition: {
// 采用的 openapi 版本。***注意该版本直接影响了管网参考版本。
openapi: "3.0.0",
// 页面基本信息
info: {
title: "数字权益区块链", //设置swagger的标题。（项目名称）
version: "1.0.0", //设置版本
},
//设置锁。用于
components: {
securitySchemes: {
oauth2: {
type: "oauth2",
flows: {
authorizationCode: {
authorizationUrl: "/oauth/dialog",
tokenUrl: "/oauth/token",
},
},
},
},
},
},
// 去指定项目路径下收集 swagger 注释，用于生成swagger文档。
apis: [path.join(__dirname, "../routes/**/*.js")],
};
var swaggerJson = function (req, res) {
res.setHeader("Content-Type", "application/json");
res.send(swaggerSpec);
};
const swaggerSpec = swaggerJSDoc(options);
var swaggerInstall = function (app) {
if (!app) {
app = express();
}
// 此路径用于向YApi导入接口文档
app.get("/swagger.json", swaggerJson);
// 使用 swaggerSpec 生成 swagger 文档页面，并开放在指定路由。swagger访问前缀
app.use("/swagger", swaggerUi.serve, swaggerUi.setup(swaggerSpec));
};
module.exports = swaggerInstall;
3. At this point, the swagger settings are completed, and then the interface parameters need to be written. Take an interface in the js file under the routes folder as an example (this time, post request is taken as an example),
and then you need to write a comment above this interface. The
specific code in the following figure is as follows:
/**,
* @swagger
* /api/baseCoinBalance:
* post:
* tags:
* - 平台币 #接口分类
* summary: 测试1 #接口备注
* description: 测试 #接口描述
* consumes:
* - "application/json" #接口接收参数方式
* requestBody: #编写参数接收体
* required: true #是否必传
* content:
* application/json:
* schema: #参数备注
* type: object #参数类型
* properties:
* fromAddress:
* type: string #参数类型
* description: 发送者钱包地址 #参数描述
* example: #请求参数样例。
* fromAddress: "string"
* responses: #编写返回体
* 1000: #返回code码
* description: 获取底层币余额成功 #返回code码描述
* content:
* application/json:
* schema:
* type: object
* properties:
* res_code: #返回的code码
* type: string
* description: 返回code码
* res_msg: #返回体信息。***注意写的位置一定要和res_code对齐。
* type: string #返回体信息类型
* description: 返回信息
* 1001:
* description: 获取底层币余额失败
* */
If you need to use other methods, please refer to Pipe Network
4. Start the project, enter the swagger path http://127.0.0.1:9009/swagger in the browser , as shown in the sample below, it means the configuration is successful.
5. Import the interface document into YApi and open YApi.
6. So far, all operations of importing swagger into YApi are completed. (Will continue to update, and constantly improve nodejs to use swagger)