什么是 Swagger ?

Swagger 是一組圍繞 OpenAPI 規(guī)范構(gòu)建的開源工具，可以幫助您設(shè)計、構(gòu)建、記錄和使用 REST API。主要的 Swagger 工具 包括：

• Swagger Editor：基于瀏覽器的編輯器，您可以在其中編寫 OpenAPI 定義
• Swagger UI：將 OpenAPI 定義呈現(xiàn)為交互式文檔
• Swagger Codegen：從 OpenAPI 定義中生成服務(wù)器存根和客戶端庫
• Swagger Editor Next（beta）：基于瀏覽器的編輯器，您可以在其中編寫和查看 OpenAPI 和 AsyncAPI 定義
• Swagger Core：用于創(chuàng)建、使用和處理 OpenAPI 定義的 Java 相關(guān)庫
• Swagger Parser：用于解析 OpenAPI 定義的獨立庫
• Swagger APIDom：提供了一個單一的、統(tǒng)一的結(jié)構(gòu)，用于跨各種描述語言和序列化格式描述 API

Nest 集成 Swagger

1. 安裝依賴

pnpm add @nestjs/swagger swagger-ui-express

2. 在 main.ts 文件中定義并初始化 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);// 構(gòu)建swagger文檔const options = new DocumentBuilder().setTitle('vue3-admin').setDescription('Background system based on Nest.js + Vue3 full stack development').setVersion('1.0').build();const document = SwaggerModule.createDocument(app, options);SwaggerModule.setup('docs', app, document);await app.listen(3000);}bootstrap();

3. 啟動服務(wù)，訪問http://localhost:3000/docs，你會看到 Swagger 頁面：
   

DocumentBuilder 屬性

方法	描述
setTitle	文檔標題
setDescription	文檔描述
setVersion	文檔版本
setTermsOfService	文檔服務(wù)條款
setContact	文檔聯(lián)系信息
setLicense	文檔許可證信息
addServer	文檔服務(wù)地址
setExternalDoc	文檔外部鏈接
setBasePath	設(shè)置文檔基礎(chǔ)路徑
addTag	添加文檔標簽
addExtension	添加擴展
addSecurity	添加安全方案
addGlobalParameters	添加全局參數(shù)
addSecurityRequirements	添加安全需求
addBearerAuth	添加 Bearer Token 認證
addOAuth2	添加 OAuth2 認證
addApiKey	添加 ApiKey
addBasicAuth	添加基礎(chǔ)認證
addCookieAuth	添加 Cookie 認證
build	構(gòu)建服務(wù)

在 Nest 中使用

1. 在 DTO(響應(yīng)數(shù)據(jù)傳輸對象) 文件中使用裝飾器

 import { ApiProperty } from '@nestjs/swagger';import { IsNumberString, IsOptional, IsUUID } from 'class-validator';export class PostParamsDto {@ApiProperty({type: String,description: '崗位名稱',required: false,default: '前端工程師',})name?: string;@ApiProperty({type: String,description: '所屬組織',default: 'f45cd48b-e703-49db-91be-ae7f594e73e0',required: false,})@IsOptional()@IsUUID('all', { message: 'orgId 參數(shù)不正確' })orgId?: string;@ApiProperty({type: Number,description: '開始日期',default: 1721145600000,required: false,})@IsOptional()@IsNumberString({}, { message: '開始日期必須是時間戳格式' })startTime?: number;@ApiProperty({type: Number,description: '結(jié)束日期',default: 1721318399999,required: false,})@IsOptional()@IsNumberString({}, { message: '結(jié)束日期必須是時間戳格式' })endTime?: number;}

2. 在 Controller 控制器 中使用裝飾器

import { Controller, Get, Query } from '@nestjs/common';
import { ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger'; // swagger 接口文檔import { PostParamsDto } from './dto/params-post.dto';
import { ResponsePostDto } from './dto/response-post.dto';
import { PostManageService } from './post-manage.service';@ApiTags('智能行政-崗位管理')
@Controller('post-manage')
export class PostManageController {constructor(private readonly postManageService: PostManageService) { }/*** @description: 查詢崗位列表*/@Get()@ApiOkResponse({ type: ResponsePostDto })@ApiOperation({ summary: '獲取崗位管理列表' })findAll(@Query() params: PostParamsDto) {return this.postManageService.findAll(params);}
}

常用 Swagger 裝飾器

裝飾器	描述
@ApiTags	為控制器或方法添加標簽，用于組織 Swagger UI 文檔
@ApiOperation	為控制器方法添加操作描述，包括摘要和詳細描述
@ApiParam	描述路徑參數(shù)、請求參數(shù)或響應(yīng)參數(shù)，包括名稱、類型、描述等
@ApiBody	指定請求體的 DTO 類型，用于描述請求體的結(jié)構(gòu)
@ApiResponse	描述 API 的響應(yīng)，包括狀態(tài)碼、描述等
@ApiBearerAuth	指定請求需要攜帶 Bearer Token，用于身份驗證
@ApiProperty	為 DTO 類型的屬性添加元數(shù)據(jù)，如描述、默認值等
@ApiQuery	描述查詢參數(shù)，包括名稱、類型、描述等
@ApiHeader	描述請求頭信息，包括名稱、類型、描述等
@ApiExcludeEndpoint	標記一個控制器方法不在 Swagger UI 中顯示

效果圖

總結(jié)

在 Nest 中集成 Swagger 文檔可以幫助開發(fā)者自動生成和維護 API 文檔，Swagger 的集成提供了在線生成、?自動生成、?可操作數(shù)據(jù)庫等優(yōu)點，規(guī)范了 API 的標準化和一致性，后期還可以把 Swagger 文檔導(dǎo)入到其他平臺，例如 ApiFox

不足之處就是會增加開發(fā)者的工作量，每一個接口都需要保持注釋和裝飾器的準確性和完整性，仍然需要一定的維護工作。