express中配置swagger并配置token信息
1. 安装swagger-jsdoc
cnpm install swagger-jsdoc@1.3.0 --save
2. 在项目根目录下的config目录下新建swagger.js文件并添加配置项
// 引入swagger
const swaggerJSDoc = require('swagger-jsdoc')
// swagger定义
const swaggerDefinition = {
// openapi: '3.0.1',
info: {
title: '若依后台管理系统 Swagger API',
version: '1.0.0',
description: 'Demonstrating how to describe a RESTful API with Swagger'
},
host: 'localhost:3007',
basePath: '/', // 根地址
}
// swagger文档配置项
var options = {
// import swaggerDefinitions
swaggerDefinition: swaggerDefinition,
// path to the API docs
apis: ['./routes/*.js'] // 扫描routes文件夹下面的所有js文件
}
// 初始化swagger-jsdoc
const swaggerSpec = swaggerJSDoc(options)
module.exports = swaggerSpec
3. 在app.js中使用
// 引入swagger配置项
const swaggerSpec = require('./config/swagger')
app.get('/swagger.json', function(req, res) {
res.setHeader('Content-Type', 'application/json')
res.send(swaggerSpec)
})
4. 在项目的public文件夹下添加api-docs文件夹
4.1 引入dist文件
在项目的public文件夹下添加api-docs文件夹，将https://github.com/swagger-api/swagger-ui中的dist文件夹下的内容全部放入api-docs文件夹中。
4.2 修改配置地址
修改swagger-initializer.js文件中的url为当前项目的启动地址
url : "http://petstore.swagger.io/v2/swagger.json";
改为
url: "http://localhost:3007/swagger.json", // express项目启动端口
5. 查看swagger
http://localhost:3007/api-docs/index.html#/
get类型接口注释
/**
* @swagger
* /user/list:
* get:
* tags:
* - 用户信息
* summary: 获取用户列表
* description:
* produces:
* - application/json
* parameters:
* - name: pageSize
* in: query
* required: false
* type: Number
* - name: pageNum
* in: query
* required: false
* type: Number
* responses:
* 200:
* description: 查询成功，返回JSON格式的用户信息
* 400:
* description: 失败
*/
router.get('/user/list',AccountService.findAll)
query参数
parameters:
- name: pageSize
in: query
required: false
type: Number
- name: pageNum
in: query
required: false
type: Number
path参数
parameters:
- in: path
name: userId
required: true
description: 用户ID
post类型接口注释
/**
* @swagger
* /mine/seam/save:
* post:
* tags:
* - 用户信息
* summary: 新增用户
* produces:
* - application/json
* parameters:
* - name: seamName
* description: 用户名称
* required: true
* type: string
* - name: seamNumber
* description: 用户编号
* in: formData
* example: 煤层1
* required: true
* type: string
* responses:
* 200:
* description: 成功
* 400:
* description: 失败
*/
router.post('/mine/seam/save',AccountService.login)
put类型接口注释
/**
* @swagger
* /edit:
* put:
* tags:
* - /movies/account
* summary: 编辑用户信息接口
* description: 修改用户信息。提交表单数据，根据用户id对用户信息进行修改
* produces:
* - application/json
* parameters:
* - name: userId
* description: 用户id,用户的唯一标示符
* in: body
* required: true
* schema:
* type: string
* properties:
* userId:
* example: 1001
* - name: userName
* description: 用户名
* in: body
* required: true
* schema:
* type: string
* properties:
* userName:
* example: '张三'
* - name: userSex
* description: 用户性别
* in: body
* required: true
* schema:
* type: string
* properties:
* userSex:
* example: '男'
* - name: userAddress
* description: 用户地址
* in: body
* required: true
* schema:
* type: string
* properties:
* userAddress:
* example: '陕西省 西安市'
* responses:
* 200:
* description: 修改成功，返回JSON格式数据
* schema:
* type: object
* properties:
* code:
* type: integer
* example: 200
* msg:
* type: string
* example: "修改成功"
* 401:
* description: 修改失败，返回JSON格式数据
* schema:
* type: object
* properties:
* code:
* type: integer
* example: 401
* msg:
* type: string
* example: '修改失败'
*/
router.put('/edit',AccountService.editAccount)
delete类型接口注释
/**
* @swagger
* /user/{userId}:
* delete:
* tags:
* - 用户信息
* summary: 删除用户
* produces:
* - application/json
* parameters:
* - in: path
* name: userId
* required: true
* description: 用户ID
* responses:
* 200:
* description: 成功
* 400:
* description: 失败
*/
接口中配置Authorization
第一步：在swagger.js文件中添加相关配置
securityDefinitions: {
Authorization: {
type: 'apiKey',
in: 'header',
name: 'Authorization',
description: ''
}
}
第二步：在接口注释处添加配置
security:
- Authorization:
swagger.js文件整体配置如下：
// 引入swagger
const swaggerJSDoc = require('swagger-jsdoc')
// swagger定义
const swaggerDefinition = {
info: {
title: '若依后台管理系统 Swagger API',
version: '1.0.0',
description: 'Demonstrating how to describe a RESTful API with Swagger'
},
host: 'localhost:3007',
basePath: '/', // 根地址
produces: ['application/json', 'application/xml'],
schemes: ['http', 'https'],
securityDefinitions: {
Authorization: {
type: 'apiKey',
in: 'header',
name: 'Authorization',
description: ''
}
}
}
// swagger文档配置项
var options = {
// import swaggerDefinitions
swaggerDefinition: swaggerDefinition,
// path to the API docs
apis: ['./routes/*.js'] // 扫描routes文件夹下面的所有js文件
}
// 初始化swagger-jsdoc
const swaggerSpec = swaggerJSDoc(options)
module.exports = swaggerSpec
接口注释整体配置如下：
/**
* @swagger
* /mine/seam/list:
* get:
* tags:
* - 矿井管理-煤层信息
* summary: 获取煤层信息列表
* description:
* produces:
* - application/json
* parameters:
* - name: pageSize
* in: query
* required: false
* type: Number
* - name: pageNum
* in: query
* required: false
* type: Number
* - name: seamName
* in: query
* required: false
* type: string
* responses:
* 200:
* description: 成功
* 400:
* description: 失败
* security:
* - Authorization:
*/
swagger ui界面及配置操作如下：
参考地址
链接1
链接2
链接3
OpenAPI
