Express中swagger-autogen异常：响应字段混入请求参数

问题描述 #

在Express项目中使用swagger-autogen@2.23.1生成接口文档时，部分控制器的#swagger.responses[200]配置中的description和schema字段被错误解析到请求parameters中，生成的Swagger文档出现多余的查询参数；但删除该响应配置又会缺失响应体定义，其他控制器无此异常。

异常代码示例 #

控制器代码：

export const getDiary = async (req: Request, res: Response) => {
  /* 
    #swagger.tags = ['Diary']
    #swagger.description = 'Get all Diary entries'
    #swagger.parameters['date'] = {
      in: 'query',
      description: 'Date of diary entry',
      required: false,
    }
    #swagger.responses[200] = {
      description: 'Diary entries successfully obtained',
      schema: { $ref: '#/definitions/DiaryResponse'}
    }
  */

  let { date } = req.query;

  const mappedRows = date
    ? await DiaryService.getAllDiaryEntriesByDate(date as string)
    : await DiaryService.getAllDiaryEntries();

  let response: HttpResponse<Diary[]> = {
    data: mappedRows,
    length: mappedRows.length,
  };

  return res.status(RESPONSE_CODES.OK).send(response);
};

生成的异常Swagger片段：

"/api/diary/": {
      "get": {
        "tags": [
          "Diary"
        ],
        "description": "Get all Diary entries",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "description": "Date of diary entry",
            "required": false,
            "type": "string"
          },
          {
            "name": "description", // 此处不应存在
            "in": "query",
            "type": "string"
          },
          {
            "name": "schema", // 此处不应存在
            "in": "query",
            "type": "string"
          }
        ],

解决方案 #

1. 修正注解的JSON格式 #

swagger-autogen对注释内的JSON格式敏感，多余的逗号或不规范的缩进会导致解析错误：

• 删除parameters['date']对象末尾的多余逗号
• 保证responses[200]内部字段的缩进统一

修改后的注解示例：

/* 
  #swagger.tags = ['Diary']
  #swagger.description = 'Get all Diary entries'
  #swagger.parameters['date'] = {
    in: 'query',
    description: 'Date of diary entry',
    required: false
  }
  #swagger.responses[200] = {
    description: 'Diary entries successfully obtained',
    schema: { $ref: '#/definitions/DiaryResponse' }
  }
*/

2. 升级swagger-autogen版本 #

2.23.1版本存在已知的注解解析bug，升级到最新稳定版可直接修复这类问题：

npm install swagger-autogen@latest --save-dev

3. 使用简化的响应注解格式 #

如果格式修正无效，可尝试swagger-autogen提供的简化响应定义写法：

/* 
  #swagger.tags = ['Diary']
  #swagger.description = 'Get all Diary entries'
  #swagger.parameters['date'] = {
    in: 'query',
    description: 'Date of diary entry',
    required: false
  }
  #swagger.response(200, 'Diary entries successfully obtained', { $ref: '#/definitions/DiaryResponse' })
*/

验证 #

修改后重新执行Swagger文档生成命令，检查生成的文档中：

• 请求parameters列表不再包含description和schema字段
• 200响应的description和schema定义正常显示

内容的提问来源于stack exchange，提问作者Kamil Naja