如何在swagger-autogen中引用Joi Schema定义查询参数

1. 确保Schema已注册到Swagger Definitions #

首先要保证转换后的Swagger Schema已正确添加到swagger-autogen的配置definitions中，否则$ref会找不到对应定义：

const swaggerAutogen = require('swagger-autogen')();
// 假设已通过j2s转换好目标Schema
const { swagger: updateCategoryBodySwagger } = j2s(你的Joi查询参数Schema);

const doc = {
  info: { /* 文档基本信息，如标题、版本等 */ },
  definitions: {
    // 注册Schema，key需与$ref中的名称完全一致
    updateCategoryBodySwagger: updateCategoryBodySwagger,
    createCategoryBodySwagger: createCategoryBodySwagger
  }
};

// 执行Swagger文档生成
swaggerAutogen('./swagger-output.json', ['./routes/*.js'], doc);

2. 使用正确的Query参数注释格式 #

你之前的写法核心逻辑没问题，但需修正细节并保证格式严谨：

• 确保$ref路径与definitions中的key完全匹配
• 描述需与接口功能匹配
• 可按需指定参数是否必填

正确注释示例：

/*
  #swagger.start
  #swagger.tags = ['Categories']
  #swagger.path = '/api/v1/categories/'
  #swagger.method = 'get'
  #swagger.summary = 'Get Categories'
  #swagger.parameters['query'] = {
    in: 'query',
    description: '分类查询筛选参数',
    schema: { $ref: '#/definitions/updateCategoryBodySwagger' },
    // 若需强制必填，可设为true；默认false
    required: false
  }

  #swagger.responses[200] = {
    description: '成功获取分类列表',
    schema: { type: 'array', items: { $ref: '#/definitions/你的分类响应Schema' } }
  }
  #swagger.responses[404] = {
    description: '未找到对应分类'
  }
  #swagger.end
*/

3. 验证生成结果 #

运行swagger-autogen后，打开生成的swagger-output.json检查：

• definitions节点下是否存在updateCategoryBodySwagger
• 对应GET接口的parameters数组中，query参数的schema.$ref是否正确指向#/definitions/updateCategoryBodySwagger

若仍不生效，打印updateCategoryBodySwagger确认转换后的结构是否符合Swagger规范（需包含type、properties等核心字段）。

内容的提问来源于stack exchange，提问作者Armen Sanoyan