Nodejs Nestjs插件swagger-ui-express实现API文档自动生成与使用

Nodejs Nestjs插件swagger-ui-express实现API文档自动生成与使用
在NestJS中使用Swagger（通过@nestjs/swagger和swagger-ui-express）来实现API文档的自动生成是一个非常便捷的过程。下面我将指导你如何配置并使用它。

1. 安装依赖

首先，你需要安装@nestjs/swagger和swagger-ui-express以及必要的类型定义：

npm install @nestjs/swagger swagger-ui-express
npm install -D @types/swagger-ui-express

2. 配置Swagger模块

接下来，在你的应用中创建一个Swagger模块。通常这会在主模块（通常是AppModule）中完成，但也可以单独创建一个模块。

创建Swagger模块

import { Module } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

@Module({
  imports: [],
  controllers: [],
  providers: [],
})
export class AppModule {
  static async initialize(app) {
    const options = new DocumentBuilder()
      .setTitle('Your API Title')
      .setDescription('Your API Description')
      .setVersion('1.0')
      .addTag('your-tag-name')
      .build();
    
    const document = SwaggerModule.createDocument(app, options);
    SwaggerModule.setup('api', app, document);
  }
}

然后在你的主文件（如main.ts）中调用这个方法：

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await AppModule.initialize(app);
  await app.listen(3000);
}
bootstrap();

3. 在控制器中添加Swagger注解

在你的控制器中，你可以使用Swagger提供的装饰器来描述你的API端点。例如：

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

@ApiTags('example')
@Controller('example')
export class ExampleController {

  @Get(':id')
  @ApiOperation({ summary: '获取示例数据' })
  @ApiResponse({ status: 200, description: '成功获取数据' })
  @ApiResponse({ status: 404, description: '未找到数据' })
  getExample(@Param('id') id: string) {
    // 实现逻辑
  }

  @Post()
  @ApiOperation({ summary: '创建示例数据' })
  @ApiResponse({ status: 201, description: '数据创建成功' })
  @ApiResponse({ status: 400, description: '无效的数据' })
  createExample(@Body() body: any) {
    // 实现逻辑
  }
}

4. 运行你的应用

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

以上就是如何在NestJS项目中使用Swagger来自动生成API文档的完整步骤。这不仅帮助开发者快速理解API接口，也方便了前端和其他服务的集成测试。


3 回复

当然，没问题！在NestJS中集成Swagger非常简单，虽然它用的是@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 { YourModule } from './your.module';

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

  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框架时，我们可以利用@nestjs/swagger和swagger-ui-express来生成和展示API文档。这里将分步骤介绍如何设置和使用。

1. 安装必要的依赖

首先需要安装@nestjs/swagger和swagger-ui-express，以及Swagger核心库swagger-jsdoc（可选，如果你想要更定制化的Swagger配置）：

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

2. 配置Swagger模块

接下来，在你的NestJS项目中配置Swagger模块。你可以在AppModule或一个独立的模块中进行如下配置：

import { Module } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule as YourAppModule } from './your-app.module';

@Module({
  imports: [
    // 其他模块...
  ],
})
export class AppModule {
  static async forRoot() {
    const app = await NestFactory.create(YourAppModule);

    const config = new DocumentBuilder()
      .setTitle('Your API Title')
      .setDescription('Your API description')
      .setVersion('1.0')
      .addTag('Your API Tags')
      .build();
    
    const document = SwaggerModule.createDocument(app, config);
    SwaggerModule.setup('api', app, document);
    
    await app.listen(3000);
  }
}

上述代码片段中，DocumentBuilder用于创建Swagger文档的基本配置，如标题、描述、版本等信息。SwaggerModule.createDocument则基于这些配置生成实际的Swagger JSON文档，最后通过SwaggerModule.setup方法将该文档暴露给Swagger UI展示。

3. 使用装饰器添加文档注释

在控制器和服务中，你可以使用各种装饰器（如@ApiOperation, @ApiQuery, @ApiResponse等）来为你的端点添加更多的文档注释，帮助自动生成更详细的API文档。

例如：

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

@Controller('users')
export class UserController {
  @Get(':id')
  @ApiOperation({ summary: 'Get user by ID' })
  @ApiResponse({ status: 200, description: 'Returns the user object' })
  @ApiResponse({ status: 404, description: 'User not found' })
  getUser(@Param('id') id: string) {
    // 业务逻辑
  }
}

以上步骤就完成了基本的Swagger集成，它会自动从你的控制器和方法中提取信息，并生成相应的API文档页面，通常可在/api路径访问。

注意：确保在生产环境中禁用Swagger文档的生成和展示，以避免安全风险。

NestJS 框架集成了 Swagger 来自动生成 API 文档。首先安装 @nestjs/swagger 和 swagger-ui-express：

npm install @nestjs/swagger swagger-ui-express

然后，在模块中导入 SwaggerModule：

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('API Title')
    .setDescription('API Description')
    .setVersion('1.0')
    .addTag('example-tag')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

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

启动应用后，访问 /api 即可查看生成的 API 文档。

回到顶部