Nest.js 使用 SwaggerSwagger api 详解装饰器作用范围作用示例 @ApiOperatio

Swagger

作用

Swagger 是一个用于设计、构建、文档和使用 RESTful Web服务的强大工具。它的主要作用如下：

API 文档生成：Swagger 可以自动从您的代码中提取 API 信息并生成交互式的 API 文档。这个文档提供了对 API 的清晰和易于理解的描述，包括端点、HTTP 方法、请求参数、响应格式等信息。
API 可视化：Swagger UI 是 Swagger 的一个组件，提供了一个直观的用户界面，允许开发者和团队成员浏览、测试和调试 API。它允许用户通过 UI 界面发送请求，查看响应并了解 API 的工作方式。
自动化代码生成：Swagger 可以根据 API 文档自动生成客户端和服务器端代码。这可以显著减少开发工作，因为开发者无需手动编写与 API 交互的代码，而是根据生成的代码进行工作。
标准化 API 设计：Swagger 鼓励采用标准的 API 设计约定，例如 OpenAPI 规范，以确保 API 在不同的编程语言和平台之间具有一致的结构和表现形式。
API 测试：Swagger UI 允许开发者轻松地测试 API，检查其行为和响应，以确保它们按预期工作。这有助于识别和解决潜在的问题。
团队协作：Swagger 提供了一个统一的方式来描述和共享 API，这有助于团队成员之间的协作，以及与外部团队、合作伙伴和第三方开发者之间的沟通。
API 安全性：Swagger 可以帮助您设计和实施 API 安全性，包括身份验证和授权。您可以在文档中明确说明哪些端点需要身份验证，以及如何进行身份验证。
版本控制：Swagger 可以帮助您管理 API 的版本控制，确保旧版本仍然可用，并记录每个版本的变化。

总的来说，Swagger 是一个非常有用的工具，可以大大简化 API 的设计、开发、测试和文档化过程，提高了开发团队的效率，同时提供了更好的可用性和可维护性。

api 详解

装饰器	作用范围	作用	示例
`@ApiOperation()`	Method	用于描述单个路由处理程序方法的操作。您可以指定操作的标题、描述、摘要等信息。	@ApiOperation({ summary: 'Get all cats', description: 'Get a list of all cats' })
`@ApiResponse()`	Method / Controller	用于描述路由处理程序方法的响应。您可以指定响应的HTTP状态码、描述和响应模型。	@ApiResponse({ status: 200, description: 'The cats have been successfully retrieved.' })
`@ApiProduces()`	Method / Controller
`@ApiConsumes()`	Method / Controller
`@ApiExtraModels()`	Method / Controller
`@ApiBody()`	Method
`@ApiParam()`	Method
`@ApiQuery()`	Method		@ApiQuery({ name: 'role', enum: UserRole })
`@ApiHeader()`	Method / Controller	要定义自定义 HTTP 标头作为请求一部分
`@ApiExcludeEndpoint()`	Method
`@ApiTags()`	Method / Controller	指定标签，用于对 API 路由进行分类和组织
`@ApiProperty()`	Model	类属性修饰
`@ApiPropertyOptional()`	Model	避免显式地输入 {{"@ApiProperty({ required: false })"}}，你可以使用 @ApiPropertyOptional() 短手装饰器。
`@ApiHideProperty()`	Model
`@ApiExtension()`	Model

nest.js中使用步骤

安装

yarn add @nestjs/swagger swagger-ui-express

main.ts中引入

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  // 配置 Swagger 文档
  const config = new DocumentBuilder()
    .setTitle('Your API Title')
    .setDescription('Your API Description')
    .setVersion('1.0')
    .addTag('Your Tag')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  // 启用 Swagger UI
  SwaggerModule.setup('api-docs', app, document);

  await app.listen(3000);
}
bootstrap();

使用

简化`@ApiProperty()`

在nest-cli.json配置

{
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "plugins": ["@nestjs/swagger/plugin"]
  }
}

`@ApiProperty()`的详细使用(类型映射，枚举)

类型映射

PartialType()函数返回一个类型（类），并将所有输入类型设置为可选的
PickType()功能从一个输入类型中选择一部分属性来创建一个新类型（类）
OmitType()函数从一个输入类型中取出所有属性然后移除一些键我们可以生成并获取一个，OmitType的第二个参数是属性名称的数组
IntersectionType()函数将两种类型组合成一个新类型（类）
类型映射函数是可以组合的。例如，下列示例将产生一个类（类型），其拥有name除外的CreateCatDto类型的所有属性，这些属性都被设置为可选的

export class UpdateCatDto extends PartialType(
  OmitType(CreateCatDto, ['name'] as const),
) {}

枚举

@ApiProperty({ enum: ['Admin', 'Moderator', 'User']})
role: UserRole;

配合@ApiQuery()使用，让query参数变成可选

@ApiQuery({ name: 'role', enum: UserRole })
async filterByRole(@Query('role') role: UserRole = UserRole.User) {}

如果希望是多选，则设置isArray为true

安全&认证

装饰器	作用范围
`@ApiBearerAuth()`	Method / Controller
`@ApiOAuth2()`	Method / Controller
`@ApiBasicAuth()`	Method / Controller
`@ApiSecurity()`	Method / Controller

注意：认证装饰器使用前都需要，使用DocumentBuilder来向你的基础文档添加安全定义

Nest.js 使用 Swagger