本文档介绍如何使用 Swagger/OpenAPI 为 NestJS 应用程序自动生成 API 文档。它涵盖了 @nestjs/swagger 模块的集成，该模块提供了装饰器和实用工具，用于以结构化的方式描述您的 RESTful API，这些描述可以显示在用户友好的 UI 中并导出为 OpenAPI 规范。
来源： sample/11-swagger/package.json24-25
OpenAPI（以前称为 Swagger）是一种用于描述、生产、消费和可视化 RESTful Web 服务的机器可读接口文件的规范。NestJS 通过其专用的 @nestjs/swagger 包提供对 OpenAPI 的一流支持。
借助 NestJS Swagger 集成，您可以：
要开始在您的 NestJS 应用程序中使用 Swagger，您需要安装必需的包
来源： sample/11-swagger/package.json24-25
设置过程包括初始化 Swagger 文档生成器并将 Swagger UI 挂载到应用程序中的特定路径。
标题：NestJS 应用程序启动中的 Swagger 集成流程
要将 Swagger 集成到您的 NestJS 应用程序中，您通常需要在您的 main.ts 文件中进行配置
DocumentBuilder 提供了各种方法来定制您的 API 文档
| 方法 | 描述 |
|---|---|
setTitle() | 设置 API 的标题 |
setDescription() | 提供 API 的描述 |
setVersion() | 设置 API 版本 |
addTag() | 添加一个标签，用于对操作进行分组 |
addBearerAuth() | 添加 Bearer 身份验证文档 |
addOAuth2() | 添加 OAuth2 身份验证文档 |
addApiKey() | 添加 API 密钥身份验证文档 |
addBasicAuth() | 添加基本身份验证文档 |
addSecurity() | 添加自定义安全文档 |
NestJS Swagger 提供了装饰器来文档化各种 API 组件，包括控制器、方法、参数和数据模型。
标题：Swagger 装饰器与 API 组件的关系
您可以使用装饰器来文档化控制器和路由
可以使用 @ApiProperty() 装饰器来文档化数据传输对象 (DTO) 和实体
您可以使用特定详细信息文档化不同的响应场景
可以文档化路径参数、查询参数和请求体
NestJS Swagger 提供了内置装饰器来文档化身份验证
您可以文档化模型之间的继承关系
为响应指定不同的内容类型
文档化文件上传端点
Swagger 与 NestJS 验证管道和 class-validator 装饰器无缝协作
标题：Swagger 与 NestJS 中验证的集成
当您在 DTO 上使用 class-validator 装饰器时，验证规则可以反映在您的 Swagger 文档中
来源： sample/11-swagger/package.json24-25 sample/11-swagger/package.json26-27
您可以自定义 Swagger UI 的外观和行为
您可以为不同的 API 部分或版本设置多个 Swagger 文档实例
您可以将 OpenAPI 规范导出到文件，以便与其他工具一起使用
使用描述性的 API 操作和响应： 为所有操作和响应类型提供有意义的描述。
一致地文档化身份验证： 在所有受保护的路由中使用一致的身份验证装饰器。
利用枚举类型： 在 TypeScript 中使用枚举来文档化字段的可能值。
对相关端点进行分组： 在 Swagger UI 中使用 @ApiTags 对相关端点进行分组。
包含示例： 在 @ApiProperty 装饰器中提供真实的示例，以帮助 API 消费者理解预期的值。
生成客户端代码： 使用导出的 OpenAPI 规范，通过 OpenAPI Generator 等工具生成客户端代码。
与验证集成： 使验证规则在您的 API 文档中可见。
来源： sample/11-swagger/package.json24-25 sample/11-swagger/package.json26-27
@nestjs/swagger 模块为您的 NestJS 应用程序提供了一种强大的方式来自动生成全面的 API 文档。通过使用提供的装饰器和实用工具，您可以创建详细、交互式的文档，帮助开发人员有效地理解和使用您的 API。
有关 NestJS 中其他高级功能的更多信息，请参阅 身份验证和授权，了解有关保护 API 端点的详细信息。