NestJS Swagger 使用教程

NestJS Swagger 使用教程

swaggerOpenAPI (Swagger) module for Nest framework (node.js) :earth_americas:项目地址:https://gitcode.com/gh_mirrors/sw/swagger

项目介绍

NestJS Swagger 是一个用于 NestJS 框架的模块，它能够帮助开发者自动生成 API 文档。通过集成 Swagger UI，开发者可以轻松地为他们的 RESTful API 创建美观且功能强大的文档。NestJS Swagger 利用 OpenAPI 规范（以前称为 Swagger 规范），使得 API 文档的生成和管理变得更加标准化和便捷。

项目快速启动

安装

首先，确保你已经安装了 NestJS CLI，然后创建一个新的 NestJS 项目：

npm i -g @nestjs/cli
nest new project-name
cd project-name

接下来，安装 Swagger 模块：

npm install --save @nestjs/swagger swagger-ui-express

配置

在 main.ts 文件中配置 Swagger：

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);

  const config = new DocumentBuilder()
    .setTitle('API 文档')
    .setDescription('API 描述')
    .setVersion('1.0')
    .addTag('api')
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

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

运行

启动应用：

npm run start

访问 http://localhost:3000/api，你将看到生成的 Swagger 文档。

应用案例和最佳实践

应用案例

假设我们有一个简单的用户管理 API，包含创建用户、获取用户列表和获取单个用户的功能。

import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
import { UserService } from './user.service';
import { User } from './user.entity';

@ApiTags('users')
@Controller('users')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Post()
  @ApiOperation({ summary: '创建用户' })
  @ApiResponse({ status: 201, description: '用户已创建', type: User })
  create(@Body() user: User): User {
    return this.userService.create(user);
  }

  @Get()
  @ApiOperation({ summary: '获取用户列表' })
  @ApiResponse({ status: 200, description: '返回用户列表', type: [User] })
  findAll(): User[] {
    return this.userService.findAll();
  }

  @Get(':id')
  @ApiOperation({ summary: '获取单个用户' })
  @ApiResponse({ status: 200, description: '返回单个用户', type: User })
  findOne(@Param('id') id: string): User {
    return this.userService.findOne(id);
  }
}

最佳实践

1. 使用 ApiTags 对 API 进行分类：这有助于组织和导航 API 文档。
2. 为每个 API 操作添加详细的描述和响应：这有助于其他开发者理解 API 的功能和预期行为。
3. 使用 ApiResponse 明确响应的状态码和数据类型：这有助于确保 API 文档的准确性和一致性。

典型生态项目

NestJS Swagger 通常与其他 NestJS 模块和工具一起使用，以构建完整的后端服务。以下是一些典型的生态项目：

1. TypeORM：一个用于 NestJS 的 ORM 库，用于数据库操作。
2. Passport：一个用于 NestJS 的身份验证库，支持多种身份验证策略。
3. GraphQL：一个用于 NestJS 的 GraphQL 模块，用于构建 GraphQL API。

通过这些生态项目的结合使用，开发者可以构建出功能丰富且易于维护的后端服务。

swaggerOpenAPI (Swagger) module for Nest framework (node.js) :earth_americas:项目地址:https://gitcode.com/gh_mirrors/sw/swagger