【Nest教程】集成Swagger自動生成接口文檔

Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。Swagger 的目標是對 REST API 定義一個標準且和語言無關的接口，可讓人和計算機擁有無須訪問源碼、文檔或網絡流量監測就能夠發現和理解服務的能力。當經過 Swagger 進行正肯定義，用戶能夠理解遠程服務並使用最少實現邏輯與遠程服務進行交互。與爲底層編程所實現的接口相似，Swagger 消除了調用服務時可能會有的猜想。

現現在，先後臺開發分離已成爲一種標準，後臺負責提供api，其他功能交給前臺來實現，可是項目開發中的溝通成本也隨之提升，這部分紅本主要體如今前臺須要接口文檔，可是後臺可能沒時間寫或者其餘緣由，致使功能對接緩慢。Swagger很好的解決了這個問題，它能夠動態生成Api接口文檔，今天咱們簡單說下在Nest項目中集成Swagger。

1 安裝Swagger

yarn add @nestjs/swagger swagger-ui-express --save

2 配置Swagger

須要在src目錄下main.ts文件中配置及構建出口，內容以下：

1import { NestFactory } from '@nestjs/core';
 2import { ValidationPipe } from '@nestjs/common';
 3import { NestExpressApplication } from '@nestjs/platform-express';
 4import { AppModule } from './app.module';
 5// 過濾器
 6import { HttpExceptionFilter } from './filters/http-exception.filter';
 7// 自定義攔截器
 8import { TransformInterceptor } from './interceptor/transform.interceptor';
 9// api文檔插件
10import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
11
12async function bootstrap() {
13  const app = await NestFactory.create<NestExpressApplication>(AppModule);
14  app.useGlobalFilters(new HttpExceptionFilter());
15  app.useGlobalInterceptors(new TransformInterceptor());
16  app.useGlobalPipes(new ValidationPipe()); //開啓一個全局驗證管道
17  const options = new DocumentBuilder()
18    .setTitle('接口文檔')
19    .setDescription('系統接口文檔') // 文檔介紹
20    .setVersion('1.0.0') // 文檔版本
21    .build();
22  // 爲了建立完整的文檔（具備定義的HTTP路由），咱們使用類的createDocument()方法SwaggerModule。此方法帶有兩個參數，分別是應用程序實例和基本Swagger選項。
23  const document = SwaggerModule.createDocument(app, options);
24  SwaggerModule.setup('/api', app, document);
25  await app.listen(3000);
26}
27bootstrap();

這裏面咱們只關注十、1三、17到24行，

DocumentBuilder 有助於構建符合 OpenAPI 規範的基礎文檔。它提供了幾種容許設置諸如標題，描述，版本等屬性的方法。爲了建立一個完整的文檔（使用已定義的 HTTP 路由），咱們使用 SwaggerModule 類的 createDocument() 方法。此方法接收兩個參數，即應用程序實例和 Swagger 選項對象。

一旦建立完文檔，咱們就能夠調用 setup() 方法。它接收：

1. Swagger UI 的掛載路徑

2. 應用程序實例

3. 上面已經實例化的文檔對象

3 啓動項目

1yarn start

應用程序運行時，打開瀏覽器並導航到 http://localhost:3000/api 。你應該能夠看到 Swagger UI

4 其餘配置項

還提供不少配置項，如ApiQuery、ApiBody、ApiParam、ApiHeader、ApiHeaders等，這裏就不一一介紹了，有興趣能夠瀏覽官方文檔：

1https://docs.nestjs.com/openapi/introduction