TSED框架中隐藏Swagger文档中的查询参数

在TSED框架开发过程中，开发者有时需要隐藏某些API参数不在Swagger文档中显示，特别是对于敏感信息或内部使用的参数。本文将深入探讨如何在TSED中实现这一需求。

问题背景

在TSED框架中，开发者经常使用@Hidden装饰器来隐藏控制器类或方法，使其不出现在Swagger文档中。然而，当尝试将此装饰器应用于查询参数或模型属性时，发现它并不能按预期工作，参数仍然会显示在生成的OpenAPI文档中。

现有解决方案分析

TSED框架目前提供了@Groups装饰器作为替代方案，它主要用于控制属性的序列化和文档生成。使用方式如下：

class FileUploadParameters {
    @Optional()
    @Groups("!summary") // 使用"!"前缀表示排除
    public secret_token?: string;
}

@Controller("/example")
class ExampleController {
    public async addEntry(
        @QueryParams() @Groups("summary") 
        params: FileUploadParameters
    ): Promise<unknown> {
        // 控制器逻辑
    }
}

这种方法的局限性在于：

1. @Groups不仅影响文档生成，还会影响JSON序列化/反序列化过程
2. 被排除的属性在请求处理中也会被忽略，可能不符合业务需求

技术实现原理

TSED框架的文档生成和数据处理共享同一套模型定义系统。这种设计虽然保证了数据一致性，但也限制了单独控制文档显示的能力。@Hidden装饰器原本设计仅用于控制器和方法级别，不适用于属性级别。

最佳实践建议

针对不同场景，推荐以下解决方案：

1. 敏感认证信息：应使用HTTP头部(Header)而非查询参数传递

   @UseBefore(MyAuthMiddleware)
   public async secureEndpoint(
       @HeaderParams("Authorization") token: string
   ): Promise<unknown> {
       // 认证逻辑
   }
   

2. 内部追踪参数：可考虑使用自定义装饰器扩展功能

   // 自定义装饰器实现
   export function Internal() {
       return applyDecorators(
           Optional(),
           Description("内部使用参数"),
           // 其他需要的装饰器
       );
   }
   

3. 临时解决方案：通过文档描述注明参数用途

   @Property()
   @Description("内部使用，请勿在文档中公开")
   public tracking_id?: string;
   

框架设计思考

从框架设计角度看，理想的解决方案应该：

• 保持数据模型定义的单一真实性
• 允许灵活控制文档生成行为
• 不影响实际业务数据处理

未来TSED可能会扩展@Hidden功能或引入专门的文档控制装饰器，以更好地满足这类需求。

总结

在现有TSED版本中，完全隐藏查询参数同时保持其功能完整存在一定挑战。开发者应根据具体业务场景选择合适方案，优先考虑将敏感信息移至HTTP头部，或使用明确的文档说明来管理参数可见性。理解框架设计哲学有助于找到最合适的实现方式。