Swagger + Nest.js：打通全栈之路，API 文档生成的秘籍

咖啡加剁椒

于 2024-05-20 20:51:53 发布

阅读量541

点赞数 17

分类专栏：软件测试文章标签： javascript 开发语言 ecmascript 软件测试自动化测试功能测试程序人生

本文链接：https://blog.csdn.net/nhb687095/article/details/139074405

版权

软件测试专栏收录该内容

904 篇文章 24 订阅

订阅专栏

Swagger 是一套开源的软件框架，它帮助开发者设计、构建、记录以及使用 RESTful Web 服务。

它包括了多个与API开发有关的开源工具，主要用于以下几个方面：

1.API 设计和定义：通过 Swagger 规范（OpenAPI），可以以YAML或JSON格式编写API定义。
2.文档自动生成：根据API定义自动生成交互式API文档，让前端开发和测试人员能够了解如何使用API，通常通过Swagger UI来展示。
3.代码生成：Swagger Codegen 可以根据API定义生成服务器存根、API 客户端库和API 文档等。
4.API 测试：Swagger 提供工具支持API的自动化测试。

安装依赖

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

配置swagger 模块


import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';


export const swaggerConfig = new DocumentBuilder()

.setTitle('海军 记账后台服务')

.setDescription('你的专属记账服务')

.setVersion('1.0')

.build();


export const createSwaggerDocument = (app) => {

const document = SwaggerModule.createDocument(app, swaggerConfig);

SwaggerModule.setup('docs', app, document);

};

DocumentBuilder 是 Swagger 模块中的一个类，用于构建 Swagger 文档的基本信息。createSwaggerDocument 函数接收一个 Nest.js 应用实例 app 作为参数。
SwaggerModule.createDocument(app, swaggerConfig) ：根据传入的应用实例和之前构建的文档配置对象，创建 Swagger 文档。
SwaggerModule.setup('docs', app, document) ：将生成的 Swagger 文档设置在指定的路径上（这里是 '/docs'），以便 Swagger UI 可以通过该路径访问文档。

DocumentBuilder常用的属性配置

在主模块引入 swagger 模块


import { NestFactory } from '@nestjs/core';

import { AppModule } from './app.module';

import { swaggerConfig, createSwaggerDocument } from './config/swagger.config';



async function bootstrap() {

const app = await NestFactory.create(AppModule);

createSwaggerDocument(app);

await app.listen(3000);

}

bootstrap();

在控制器中使用装饰器来标识 swagger

控制器中使用 @ApiTags() 、 @ApiOperation() 、 @ApiResponse() 等装饰器来定义 API 文档。


@Post()

@ApiOperation({ summary: '添加流水信息', tags: ['Cost Records'] }) // 添加 API 操作的摘要

@ApiBody({ type: CreateCostRecordDto }) // 指定请求体的 DTO 类型

@ApiResponse({ status: 201, }) // 添加成功响应信息

@ApiResponse({ status: 400, }) // 添加错误响应信息，根据实际需要添加更多

create(@Body() createCostRecordDto: CreateCostRecordDto) {

return this.costRecordService.create(createCostRecordDto);

}

常用的Swagger 装饰器