使用swagger
下载依赖包
npm install swagger-ui-express swagger-jsdoc --save
:下载所需要的依赖包。
配置swagger.js
文件用于后面中间件的使用
const swaggerJsDoc = require("swagger-jsdoc")
:引入并将实例赋值给一个变量。
定义definition
内的设置
openapi
:openapi的版本,最新下载的swagger依赖都为3.0.0以上版本。info
:文档页面顶部的描述信息。
title
:标题。
version
:当前版本。
description
:描述。components
:全局自定义组件。接口相应位置通过$ref: '#/components/xxx/xxx'
使用。
parameters
:定义全局参数,query传参和设置header请求头使用。
XCustomHeader
:自定义组件名。
in: "header"
:指定参数位置,header
表示请求头,query
表示query的传参。
name: "X-Custom-Header"
:header内请求头名称,query内参数名称。
type: "string"
:参数类型。
description: "改变请求头X-Custom-Header"
:描述。
required: true
:是否必填。
securitySchemes
:定义全局安全方案机制。
jwtAuth
:自定义安全方案名称。
type: "http"
:安全方案的类型,http类型用于定义基于HTTP/S协议的安全方案。
scheme: "bearer"
:指定认证方案类型,bearer表示持有者令牌(bearer token)。
bearerFormat: "JWT"
:指定bearer后面的令牌类型,Bearer JWT。servers
:服务配置,servers
内的url
配置接口文档中访问api的根目录,可配置多个。
配置apis
访问路径和文件类型
- 配置访问哪个文件夹下的哪种文件,
["./*.js"]
表示访问当前目录文件夹下所有的js文件。["./router*.js"]
表示访问roter文件夹下的所有js文件。
swaggerJsDoc()
方法使用配置
const swaggerJsDoc = require("swagger-jsdoc")
:引入swaggerJsDoc
。const specs = swaggerJsDoc(options)
:使用配置文件并赋值给一个变量。
示例
const swaggerJsDoc = require("swagger-jsdoc");
const options = {
definition: {
openapi: "3.1.0",
info: {
title: "花城api文档",
version: "1.0.0",
description:
"nodejs+express+mysql+swagger+aliyunoss实现花城小程序后台api文档",
},
components: { // 全局自定义组件
parameters: { // 定义全局参数,query传参和设置header请求头使用
XCustomHeader: { // 自定义组件名
in: "header", // 指定参数位置 header表示请求头 path表示get的query的传参
name: "X-Custom-Header", // 参数名称
type: "string", // 指定参数类型
description: "改变请求头X-Custom-Header", // 描述
required: true, // 是否必填
},
},
securitySchemes: { // 定义全局安全方案机制 使用的时候security内调用 security: - jwtAuth: []
jwtAuth: { // 自定义安全方案名称
type: "http", // 指定安全方案的类型,http类型用于定义基于HTTP协议的安全方案 包括scheme内bearer、basic、digest等子类型。https请求也使用http。
scheme: "bearer", // 指定认证方案类型,持有者令牌(bearer token)
bearerFormat: "JWT", // 指定bearer后面的令牌类型,Bearer JWT
},
},
},
servers: [
{
url: "https://tzof.net:217", // 根据实际情况修改
},
],
},
apis: ["./*.js"], // 可以指定文件或目录
};
const specs = swaggerJsDoc(options);
module.exports = specs;
在app.js
中使用中间件开启swagger文档
const swaggerUi = require("swagger-ui-express")
:引入swaggerUi并赋值给一个变量。const swaggerDocs = require("./swagger")
:引入之前创建的配置文件swagger.js
并赋值给一个变量。app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerDocs))
:使用中间件开启swagger文档。
第一个参数/api-docs
表示开启文档的路由可以通过根目录+路由访问生成的api文档。
JSDoc注释(yaml文件)的配置说明
swagger官方编辑器,可以验证yaml是否合法,也可以参考里面的yaml内容。
- 注意
:
分号不能落下,也不能使用中文的分号。 - JSDoc注释代码前面的空格会影响文档的生成,要按照yaml的格式增加空格。
- 数组属性内每次
-
就代表了一个数组内的元素。 - 在对象中如果不设置默认值为""空字符串
default: ""
在特殊情况下对应输入框内会默认显示type定义的值,如"string"。 - 在
responses
响应结果内,json格式的返回体数据无法在对应属性增加description
描述。
配置说明
@swagger
:告诉swagger-jsdoc工具,接下来的注释应该被解析为@swagger或@openapi文档的一部分。
/setUserinfo:
:接口路由。
post:
:请求方式。
summary:
:总结概述。
tags: [User]
:标签,可以将API归类到一个或多个标签下。
security:
:设置访问API的安全机制(认证机制)。
- jwtAuth: []
:使用指定的安全方案(自定义安全方案名称),在全局组件的securitySchemes定义。[]空数组表明了安全方案的参数,因为JWT通常不需要额外的参数因此这里使用空数组。
parameters:
:定义param参数。query数据传参或者设置header请求头的时候使用。
- in: query
:指定参数位置 get请求的query传参。
name: openId
:参数名称。
required: true
:是否必填。
description: 描述
:描述,注意是写在schema同层。
schema:
:开始定义内容。
type: string
:数据类型。
- in: header
:指定参数位置 设置请求头。
name: X-Custom-Header
:请求头的名称。
required: true
:是否必填。
schema:
:开始定义内容。
type: string
:数据类型。
requestBody:
:定义请求体,req.body(request body)的信息。传递application/json、multipart/form-data、application/x-www-form-urlencoded数据的时候使用。
required: true
:是否必填。对于整个请求体不是指定某个字段。
description: 描述
:对于整个请求体的描述。
content:
:开始定义请求体内容。
application/json:
:指定了请求体内容格式为json,可以为application/json、multipart/form-data、application/x-www-form-urlencoded等请求体的格式。
schema:
:开始定义内容。
type: object
:内容的数据类型。
required: ["openId"]
:指定对象内的必填字段。
properties:
:开始定义对象的属性。
openId:
:属性名,定义该属性下的配置。
type: string
:数据类型。
default: ""
:默认值。在对象中如果不设置默认值为""空字符串在特殊情况下对应输入框内会默认显示type定义的值,如"string"。
description: 用户的openId
:描述。
file:
:属性名,定义该属性下的配置。
type: string
:数据类型。
format: binary
:表示该字符串实际上是一个二进制数据流,即一个文件流。
default: ""
:默认值。
description: 上传的文件
:描述。
responses:
:响应结果,返回报文。
200:
:定义了HTTP状态码为200的时候的响应结果。
description: 成功获取用户信息
:返回结果整体描述。
content:
:开始定义返回体内容。
application/json:
:指定了返回内容类型为json。
schema:
:开始定义内容。
type: object
:内容的数据类型。
properties:
:开始定义对象的属性。
data:
:属性名。
type: string
:属性数据类型。
msg:
:属性名。
type: string
:属性数据类型。
default: 成功
:默认值。
400:
:定义了HTTP状态码为400的时候的响应结果
description: 请求参数错误
:返回结果整体描述。
说明示例
// JSDoc注释 写法说明
// https://editor.swagger.io/?spm=5176.28103460.0.0.32735d27VIMi8d 官方编辑器可以验证和参考里面的yaml文件
/**
* @swagger // 告诉swagger-jsdoc工具,接下来的注释应该被解析为@swagger或@openapi文档的一部分。
* /setUserinfo: // 接口路由
* post: // 请求方式
* summary: 根据openId获取用户信息 // 总结概述
* tags: [User] // 标签,可以将API归类到一个或多个标签下
* security: // 设置访问API的安全机制(认证机制)
* - jwtAuth: [] // 使用指定的安全方案(自定义安全方案名称),在全局组件的securitySchemes定义。[]空数组表明了安全方案的参数,因为JWT通常不需要额外的参数因此这里使用空数组。
* parameters: // 定义param参数。query数据传参或者设置header请求头的时候使用
* - in: query // 指定参数位置 get请求的query传参
* name: openId // 参数名称
* required: true // 是否必填
* description: 用户openid // 描述 注意是写在schema同层
* schema: // 开始定义内容
* type: string // 数据类型
* - in: header // 指定参数位置 设置请求头
* name: X-Custom-Header // 请求头的名称
* required: true // 是否必填
* description: 请求头 // 描述 注意是写在schema同层
* schema: // 开始定义内容
* type: string // 数据类型
* requestBody: // 定义请求体,req.body(request body)的信息。 传递application/json、multipart/form-data、application/x-www-form-urlencoded数据的时候使用
* required: true // 是否必填。对于整个请求体不是指定某个字段。
* description: 需要的请求体 // 对于整个请求体的描述。
* content: // 开始定义请求体内容
* application/json: // 指定了请求体内容格式为json,可以为application/json、multipart/form-data、application/x-www-form-urlencoded等请求体的格式
* schema: // 开始定义内容
* type: object // 内容的数据类型
* required: ["openId"] // 指定对象内的必填字段
* properties: // 开始定义对象的属性
* openId: // 属性名,定义该属性下的配置
* type: string // 数据类型
* default: "" // 默认值。在对象中如果不设置默认值为""空字符串在特殊情况下对应输入框内会默认显示type定义的值,如"string"
* description: 用户的openId // 描述
* avatarUrl: // 属性名,定义该属性下的配置
* type: string // 数据类型
* default: "" // 默认值。
* description: 头像地址 // 描述
* file: // 属性名,定义该属性下的配置
* type: string // 数据类型
* format: binary // 表示该字符串实际上是一个二进制数据流,即一个文件流。
* description: 上传的文件 // 描述
* responses: // 响应结果 返回报文
* 200: // 定义了HTTP状态码为200的时候的响应结果
* description: 成功获取用户信息 // 返回结果整体描述
* content: // 开始定义返回体内容
* application/json: // 指定了返回内容类型为json
* schema: // 开始定义内容
* type: object // 内容的数据类型
* properties: // 开始定义对象的属性
* data: // 属性名
* type: string // 属性数据类型
* msg: // 属性名
* type: string // 属性数据类型
* default: 成功 // 默认值
* 400: // 定义了HTTP状态码为400的时候的响应结果
* description: 请求参数错误 // 返回结果整体描述
*/
post请求示例
/**
* 获取用户信息
* @swagger
* /setUserinfo:
* post:
* summary: 设置用户信息
* tags: [User]
* security:
* - jwtAuth: []
* requestBody:
* content:
* application/x-www-form-urlencoded:
* schema:
* type: object
* required: ["openId"]
* properties:
* openId:
* type: string
* default: ""
* description: 用户的openId
* avatarfileName:
* type: string
* default: ""
* description: 头像文件名
* avatarUrl:
* type: string
* default: ""
* description: 头像地址
* nickname:
* type: string
* default: ""
* description: 昵称
* responses:
* 200:
* description: 成功获取用户信息
* content:
* application/json:
* schema:
* type: object
* properties:
* msg:
* type: string
* default: 创建/更新用户信息成功
*/
get请求示例
/**
* 获取用户信息
* @swagger
* /getUserinfo:
* get:
* summary: 根据openId获取用户信息
* tags: [User]
* parameters:
* - in: query
* name: openId
* required: true
* description: 用户的openId
* schema:
* type: string
* security:
* - jwtAuth: []
* responses:
* 200:
* description: 成功获取用户信息
* content:
* application/json:
* schema:
* type: object
* properties:
* openId:
* type: string
* nickname:
* type: string
* avatarfileName:
* type: string
* avatarUrl:
* type: string
*/
post请求form-data上传文件示例
/**
* 上传文件到oss
* @swagger
* /upload:
* post:
* summary: 上传文件到OSS并返回可访问地址
* tags: [OSS]
* security:
* - jwtAuth: []
* requestBody:
* content:
* multipart/form-data:
* schema:
* type: object
* required: ["file"]
* properties:
* file:
* type: string
* format: binary
* description: 上传的文件
* responses:
* 200:
* content:
* application/json:
* schema:
* type: object
* properties:
* msg:
* type: string
* default: "上传成功"
* avatarUrl:
* type: string
* fileName:
* type: string
*/