Nestia项目中TypedQuery参数在Swagger文档中的正确生成方式

在Nestia项目中，当开发者使用@TypedQuery()装饰器定义接口查询参数时，关于如何在Swagger文档中正确展示这些参数，存在一些值得探讨的技术细节。

参数展示方式的差异

当定义一个查询参数接口如：

export interface QueryShow {
  showId: string;
  otherId: string
}

并在控制器方法中使用：

public async show(@TypedQuery() query: QueryShow) {}

Nestia默认会在Swagger文档中生成以下形式的参数定义：

parameters:
  - name: query
    in: query
    schema:
      $ref: '#/components/schemas/QueryShow'
    description: ''
    required: true

然而，更符合RESTful API设计惯例的方式应该是将每个查询参数单独列出：

parameters:
  - name: showId
    in: query
    schema:
      type: string
    description: ''
    required: true
  - name: otherId
    in: query
    schema:
      type: string
    description: ''
    required: true

两种方式的对比分析

1. 默认方式：

   • 将整个查询参数对象作为一个整体展示
   • 在Swagger UI中表现为一个JSON输入框
   • 需要用户手动输入完整的JSON结构
   • 不符合大多数API文档的常规展示方式

2. 推荐方式：

   • 将每个查询参数单独列出
   • 在Swagger UI中为每个参数提供独立的输入框
   • 更符合开发者的使用习惯
   • 提供更好的用户体验和可读性

解决方案

Nestia提供了配置选项来调整这种行为。开发者可以通过设置@nestia/sdk的配置项来改变Swagger文档中查询参数的展示方式，使其更符合常规API文档的展示习惯。

最佳实践建议

1. 对于简单查询参数，建议使用单独列出的方式
2. 对于复杂嵌套对象，可以考虑使用默认的JSON结构方式
3. 根据团队和项目的实际需求选择合适的展示方式
4. 保持整个项目中参数展示方式的一致性

通过合理配置，开发者可以在保持类型安全的同时，生成更符合开发者预期的API文档，从而提高API的可用性和易用性。