node.js中使用swagger生成api接口文档,JSDoc注释(yaml文件)的配置说明

159 阅读9分钟

使用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:描述。 image.png
  • 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
 */

示例效果截图

image.png

image.png

image.png

image.png

image.png