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

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

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

1 安裝Swaggerbootstrap

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

2 配置Swaggerapi

須要在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 選項對象。app

一旦建立完文檔,咱們就能夠調用 setup() 方法。它接收:框架

  1. Swagger UI 的掛載路徑async

  2. 應用程序實例ide

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

3 啓動項目

1yarn start

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

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

4 其餘配置項

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

1https://docs.nestjs.com/openapi/introduction
相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在,都有一个你没有努力的曾经。