Nodejs Nestjs API文档插件@nestjs/swagger-ui的使用

Nodejs Nestjs API文档插件@nestjs/swagger-ui的使用
[@nestjs](/user/nestjs)/swagger 是一个用于 NestJS 项目中生成 Swagger 文档的强大工具。它可以帮助你自动生成 API 文档，并且通过 Swagger UI 可视化这些文档。这里是如何使用 [@nestjs](/user/nestjs)/swagger 和 swagger-ui-express 来为你的 NestJS 应用程序创建 API 文档。

步骤1：安装必要的依赖

首先，你需要在你的 NestJS 项目中安装 [@nestjs](/user/nestjs)/swagger 和 swagger-ui-express：

npm install [@nestjs](/user/nestjs)/swagger swagger-ui-express

步骤2：配置 Swagger

接下来，在你的应用程序中配置 Swagger。这通常在主模块（通常是 app.module.ts）中完成。

import { Module } from '[@nestjs](/user/nestjs)/common';
import { NestFactory } from '[@nestjs](/user/nestjs)/core';
import { DocumentBuilder, SwaggerModule } from '[@nestjs](/user/nestjs)/swagger';
import { AppModule as YourAppModule } from './app.module'; // 你的主模块
import * as express from 'express';

@Module({
  imports: [YourAppModule],
})
export class AppModule {
  static forRoot() {
    return AppModule;
  }
}

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // 配置Swagger
  const config = new DocumentBuilder()
    .setTitle('API Title')
    .setDescription('The API description')
    .setVersion('1.0')
    .addTag('your-tag') // 可以添加多个标签
    .build();

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

  // 如果你想同时使用 swagger-ui-express
  app.use('/swagger', express.static('node_modules/swagger-ui-express'));
  
  await app.listen(3000);
}
bootstrap();

步骤3：标记控制器和方法

为了生成正确的文档，你需要在控制器和方法上使用适当的装饰器。例如：

import { Controller, Get, Param, Query, Post, Body } from '[@nestjs](/user/nestjs)/common';
import { ApiOperation, ApiResponse, ApiTags } from '[@nestjs](/user/nestjs)/swagger';

@ApiTags('example') // 这个标签需要与你在Swagger配置中的标签相匹配
@Controller('example')
export class ExampleController {

  @Get(':id')
  @ApiOperation({ summary: '获取示例' })
  @ApiResponse({ status: 200, description: '返回示例数据' })
  getExample(@Param('id') id: string) {
    return { id };
  }

  @Post()
  @ApiOperation({ summary: '创建示例' })
  @ApiResponse({ status: 201, description: '创建成功' })
  createExample(@Body() body: any) {
    return body;
  }
}

步骤4：运行应用

启动你的 NestJS 应用后，你应该能在 http://localhost:3000/api 看到 Swagger UI 自动加载了你的 API 文档。

以上就是如何在 NestJS 中使用 [@nestjs](/user/nestjs)/swagger 创建 API 文档的基本步骤。你可以根据需要进一步定制和扩展 Swagger 的功能。