开发环境:nodejs + express
需求:需要使用swagger将接口导入到YApi中,but but but 没用过!
首先附上参考管网:https://swagger.io/docs/specification/authentication/
鉴于网上教程大多尚不完整,特此编写(仅供参考)
完成后样例:
1.在app.js文件中引入swagger
具体代码如下
require("./swagger")(app);
2.在项目下根目录下新建swagger文件夹并新建index.js文档用于编写swagger的基本设置。
具体代码如下:
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", //设置版本
},
//设置锁。用于生成swagger文档。
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.至此完成了swagger的设置,接下来需要编写接口参数。以routes文件夹下的 js文件中某个接口为例(本次以post请求为例)
然后需要在此接口的上方,编写注释,如下图
具体代码如下:
/**,
* @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: 获取底层币余额失败
* */
如需使用其他方法,请参考管网
4.启动项目,在浏览器输入swagger路径 http://127.0.0.1:9009/swagger,如下图样例所示,即为配置成功。
5.将接口文档导入YApi中,打开YApi。
6.至此完成了swagger导入到YApi中的所有操作。(会持续更新,不断完善nodejs使用swagger)