Nestia项目中如何为Swagger文档添加参数示例

在Nestia项目中，开发者经常需要为生成的Swagger文档添加参数示例，以便更清晰地展示API的使用方式。本文将详细介绍如何在Nestia中实现这一功能。

问题背景

当使用Nestia生成Swagger文档时，默认情况下不会自动显示参数的示例值。这与NestJS中的@ApiProperty({ example: 'test' })功能有所不同，导致开发者需要寻找替代方案。

解决方案

Nestia提供了通过typia库的tags模块来为参数添加示例的方法。具体实现方式如下：

import { tags } from "typia";

interface IGetHello {
  name: string &
    tags.JsonSchemaPlugin<{
      example: 'test';
    }>;
}

这种方法利用了TypeScript的类型交叉特性，将基本类型与JsonSchemaPlugin装饰器结合，为name属性添加了示例值"test"。

技术原理

1. 类型交叉：通过&操作符将基本类型与装饰器类型合并
2. JsonSchemaPlugin：typia提供的装饰器，用于修改生成的JSON Schema
3. 示例注入：在Schema中注入example字段，Swagger UI会自动识别并显示

注意事项

1. 确保项目中已安装typia作为依赖
2. 这种方法适用于接口定义中的属性级别示例
3. 对于更复杂的示例场景，可以结合其他typia装饰器使用

总结

通过使用typia的JsonSchemaPlugin，Nestia开发者可以灵活地为Swagger文档添加参数示例，提高API文档的可读性和实用性。这种方法虽然与NestJS的实现方式不同，但同样简洁有效。