Nest框架中集成使用Swagger示例說明

更新時間：2022年08月01日 08:36:40 作者：六號積極分子

這篇文章主要為大家介紹了Nest框架中集成使用Swagger的示例說明，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進步，早日升職加薪

Swagger

Swagger 是一個能夠生成、描述、調(diào)用和可視化的 RESTful 風格的 Web 服務。主要是對 REST API 接口自動生成接口說明文檔。生成的接口文檔也是直接在線測試。即在可視化的Web 界面上直接輸入?yún)?shù)對應的值就可以在線測試接口。

Nest 框架也提供了一個專門用于支持 Swagger 規(guī)范的模塊。

Nest 中使用 Swagger

安裝

首先需要安裝所需要的 swagger 包

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

初始化 Swagger

在 Nest 項目的 main.ts 文件中，使用 SwaggerModule 類初始化 Swagger

import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
async function bootstrap() {
    const options = new DocumentBuilder()
    .setTitle('Api example')
    .setDescription('The API description')
    .setVersion('1.0')
    .addTag('Api/V1')
    .build();
  const document = SwaggerModule.createDocument(app, options);
  SwaggerModule.setup('api', app, document);
}

DocumentBuilder : 先new 一個 DocumentBuilder 實例，主要是為構建符合 OpenApi規(guī)范的基礎文檔，從以上Demo中可以看到可以對 Swagger 文檔設置標題、描述、版本號、tag的相關屬性。
createDocument()：用于創(chuàng)建文檔。該方法主要接收兩個參數(shù)：一個是 app 應用程序?qū)嵗?，一個是 Swagger 選項對象。

創(chuàng)建完文件之后，即可調(diào)用 setup 方法。

配置完之后，就可以在運行項目，通過訪問 http://localhost:3000/api，就可以打開 Swagger 的可視化界面，其中就會展示所有的接口列表。

接口中使用

所有的配置都已就位，接下來就是將每個接口都配置上 swagger ，以便接口能夠展示在可視化 web界面上。

首先需要引用可支持 Swagger 的模塊

import { ApiProperty } from '@nestjs/swagger';

在使用相關支持Swagger 的裝飾器方法，比如 @ApiProperty() 裝飾器注釋所有的屬性。

@ApiTags('user')
@Controller('api/v1/user')
export class UserController {
    @Post()
    @ApiCreatedResponse({
    description: 'The record has been successfully created.',
    type: User
    })
    async CreateUser(@Body() userDto:UserDto){
      // doing something
    }
}
export class UserDto {
    @ApiProperty()
    name: string;
    @ApiProperty()
    age: number
}

ApiTags :將控制器附加到特定的標簽

@ApiResponse()：自定義 Http 響應

@ApiProperty() 為請求指定返回模型，創(chuàng)建 Dto 類并使用裝飾器注釋所有的屬性

這樣設置之后，運行項目，訪問 swagger 可視化界面就可以看到界面，并且在界面上測試該接口。