Nodejs Nestjs API文档生成插件@nestjs/swagger的使用

Nodejs Nestjs API文档生成插件@nestjs/swagger的使用
[@nestjs](/user/nestjs)/swagger 是一个非常强大的库，用于在 NestJS 项目中生成 API 文档。它基于 Swagger（现在称为 OpenAPI）规范，可以让你自动生成美观且功能丰富的 API 文档。

以下是使用 [@nestjs](/user/nestjs)/swagger 的基本步骤：

1. 安装必要的依赖

首先，你需要安装 [@nestjs](/user/nestjs)/swagger 和 swagger-ui-express：

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

2. 配置 SwaggerModule

在你的应用模块（通常是 app.module.ts）中配置 SwaggerModule：

import { NestFactory } from '[@nestjs](/user/nestjs)/core';
import { DocumentBuilder, SwaggerModule } from '[@nestjs](/user/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();

  // 使用配置对象创建 Swagger 文档
  const document = SwaggerModule.createDocument(app, config);
  // 将文档暴露给 Swagger UI
  SwaggerModule.setup('api', app, document);

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

3. 装饰你的控制器和方法

你可以使用装饰器来描述你的 API 端点、参数、响应等。例如：

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

@Controller('cats')
@ApiTags('Cats') // 添加一个标签
export class CatsController {
  @Get()
  @ApiOperation({ summary: '获取所有猫' }) // 描述这个操作
  @ApiResponse({ status: 200, description: '返回所有猫的信息' })
  findAll(@Query() query) {
    return 'This action returns all cats';
  }

  @Post()
  @ApiOperation({ summary: '创建一个新的猫' })
  @ApiResponse({ status: 201, description: '新猫创建成功' })
  create(@Body() body) {
    return 'This action adds a new cat';
  }
}

4. 运行你的应用

启动你的 NestJS 应用后，你可以在浏览器中访问 http://localhost:3000/api 来查看生成的 Swagger 文档。

5. 高级配置

  • 全局配置：你可以通过 AppModule 中的 providers 或者使用 NestJS 的 forRoot() 方法来设置全局配置。
  • 模型定义：你可以使用 @ApiProperty() 装饰器来定义模型，以便更好地描述请求体和响应结构。

通过以上步骤，你可以轻松地为你的 NestJS 应用生成高质量的 API 文档。


3 回复

当然，要给你的NestJS项目添加一个强大的API文档生成器，你可以使用@nestjs/swagger和swagger-ui-express。首先，安装它们：

npm install @nestjs/swagger swagger-ui-express

接着，在你的模块中配置Swagger：

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

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

  const config = new DocumentBuilder()
    .setTitle('你的项目名称')
    .setDescription('项目描述')
    .setVersion('1.0')
    .addTag('标签名')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

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

现在，当你启动应用后，访问/api就能看到自动生成的Swagger UI界面了！是不是很简单呢？


@nestjs/swagger 是一个非常强大的库，用于自动生成API文档，特别是当你在使用NestJS框架时。下面是一个简单的步骤来帮助你开始使用这个库。

1. 安装必要的依赖

首先，你需要安装@nestjs/swagger和swagger-ui-express：

npm install @nestjs/swagger swagger-ui-express

同时，你可能还需要安装class-validator和class-transformer来处理数据验证和转换：

npm install class-validator class-transformer

2. 配置Swagger模块

在你的NestJS应用中配置Swagger模块，通常是在app.module.ts文件中：

import { Module } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule as AppModuleClass } from './app.module'; // 假设这是你的主模块
import { AppModule } from './app.module';

@Module({
  imports: [AppModule],
})
export class AppModule {}

在main.ts文件中进行如下配置：

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

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

  const config = new DocumentBuilder()
    .setTitle('你的项目名称')
    .setDescription('项目的描述')
    .setVersion('1.0')
    .addTag('标签名') // 可以添加多个标签
    .build();
  
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

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

这里，我们创建了一个Swagger文档，并设置它在/api路径上可用。

3. 使用Swagger注解定义API

在你的控制器和服务中，你可以使用各种Swagger注解来定义你的API。例如：

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

@ApiTags('示例标签')
@Controller('example')
export class ExampleController {
  @Get()
  @ApiOperation({ summary: '获取所有示例' })
  @ApiResponse({ status: 200, description: '成功返回数据' })
  findAll(@Query() query: any) {
    return query;
  }

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

以上就是如何在NestJS应用中使用@nestjs/swagger的基本步骤。通过这种方式，你可以轻松地为你的API生成清晰且详细的文档。

[@nestjs](/user/nestjs)/swagger 是一个用于 NestJS 项目的库，用于自动生成 API 文档，通常与 Swagger（现在称为 OpenAPI）一起使用。以下是基本使用步骤：

  1. 安装必要的包：

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

  2. 在你的模块文件中引入 SwaggerModule 和配置：

    import { NestFactory } from '[@nestjs](/user/nestjs)/core';
import { DocumentBuilder, SwaggerModule } from '[@nestjs](/user/nestjs)/swagger';
import { AppModule } from './app.module';

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

  const config = new DocumentBuilder()
    .setTitle('API Title')
    .setDescription('API Description')
    .setVersion('1.0')
    .addTag('标签名')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

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

  3. 使用装饰器为控制器和方法添加描述，例如：

    [@Get](/user/Get)()
[@ApiOperation](/user/ApiOperation)({ summary: '获取列表' })
get(): string {
  return 'This action returns all cats';
}

通过这些步骤，你可以轻松地为 NestJS 项目生成详细的 API 文档。

回到顶部