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

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

Nest 中使用 Swagger

安裝

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

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

初始化 Swagger

在 Nest 項(xiàng)目的 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 一個(gè) DocumentBuilder 實(shí)例，主要是為構(gòu)建符合 OpenApi規(guī)范的基礎(chǔ)文檔，從以上Demo中可以看到可以對(duì) Swagger 文檔設(shè)置標(biāo)題、描述、版本號(hào)、tag的相關(guān)屬性。
createDocument()：用于創(chuàng)建文檔。該方法主要接收兩個(gè)參數(shù)：一個(gè)是 app 應(yīng)用程序?qū)嵗?，一個(gè)是 Swagger 選項(xiàng)對(duì)象。

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

配置完之后，就可以在運(yùn)行項(xiàng)目，通過(guò)訪問(wèn) http://localhost:3000/api，就可以打開(kāi) Swagger 的可視化界面，其中就會(huì)展示所有的接口列表。

接口中使用

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

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

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

在使用相關(guān)支持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 :將控制器附加到特定的標(biāo)簽

@ApiResponse()：自定義 Http 響應(yīng)

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

這樣設(shè)置之后，運(yùn)行項(xiàng)目，訪問(wèn) swagger 可視化界面就可以看到界面，并且在界面上測(cè)試該接口。