什么是 Swagger ?

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

• Swagger Editor：基于瀏覽器的編輯器，您可以在其中編寫 OpenAPI 定義
• Swagger UI：將 OpenAPI 定義呈現(xiàn)為交互式文檔
• Swagger Codegen：從 OpenAPI 定義中生成服務(wù)器存根和客戶端庫(kù)
• Swagger Editor Next（beta）：基于瀏覽器的編輯器，您可以在其中編寫和查看 OpenAPI 和 AsyncAPI 定義
• Swagger Core：用于創(chuàng)建、使用和處理 OpenAPI 定義的 Java 相關(guān)庫(kù)
• Swagger Parser：用于解析 OpenAPI 定義的獨(dú)立庫(kù)
• Swagger APIDom：提供了一個(gè)單一的、統(tǒng)一的結(jié)構(gòu)，用于跨各種描述語(yǔ)言和序列化格式描述 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. 啟動(dòng)服務(wù)，訪問(wèn)http://localhost:3000/docs，你會(huì)看到 Swagger 頁(yè)面：
   

DocumentBuilder 屬性

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

在 Nest 中使用

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

 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: '開(kāi)始日期',default: 1721145600000,required: false,})@IsOptional()@IsNumberString({}, { message: '開(kāi)始日期必須是時(shí)間戳格式' })startTime?: number;@ApiProperty({type: Number,description: '結(jié)束日期',default: 1721318399999,required: false,})@IsOptional()@IsNumberString({}, { message: '結(jié)束日期必須是時(shí)間戳格式' })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	為控制器或方法添加標(biāo)簽，用于組織 Swagger UI 文檔
@ApiOperation	為控制器方法添加操作描述，包括摘要和詳細(xì)描述
@ApiParam	描述路徑參數(shù)、請(qǐng)求參數(shù)或響應(yīng)參數(shù)，包括名稱、類型、描述等
@ApiBody	指定請(qǐng)求體的 DTO 類型，用于描述請(qǐng)求體的結(jié)構(gòu)
@ApiResponse	描述 API 的響應(yīng)，包括狀態(tài)碼、描述等
@ApiBearerAuth	指定請(qǐng)求需要攜帶 Bearer Token，用于身份驗(yàn)證
@ApiProperty	為 DTO 類型的屬性添加元數(shù)據(jù)，如描述、默認(rèn)值等
@ApiQuery	描述查詢參數(shù)，包括名稱、類型、描述等
@ApiHeader	描述請(qǐng)求頭信息，包括名稱、類型、描述等
@ApiExcludeEndpoint	標(biāo)記一個(gè)控制器方法不在 Swagger UI 中顯示

效果圖

總結(jié)

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

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