Swagger

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

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

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

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

接口中使用

所有的配置都已就位，接下來就是將每個接口都配置上 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() 為請求指定返回模型，創(chuàng)建 Dto 類并使用裝飾器注釋所有的屬性

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

參考資料：docs.nestjs.cn/9/recipes?i…

以上就是Nest框架中集成使用Swagger示例說明的詳細內(nèi)容，更多關(guān)于Nest框架集成Swagger的資料請關(guān)注腳本之家其它相關(guān)文章！

最新評論