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

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 模块

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

5. export const swaggerConfig = new DocumentBuilder()

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

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

11. .setVersion('1.0')

13. .build();

16. export const createSwaggerDocument = (app) => {

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

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

22. };

• DocumentBuilder 是 Swagger 模块中的一个类，用于构建 Swagger 文档的基本信息。createSwaggerDocument 函数接收一个 Nest.js 应用实例 app 作为参数。

• SwaggerModule.createDocument(app, swaggerConfig) ：根据传入的应用实例和之前构建的文档配置对象，创建 Swagger 文档。

• SwaggerModule.setup('docs', app, document) ：将生成的 Swagger 文档设置在指定的路径上（这里是 '/docs'），以便 Swagger UI 可以通过该路径访问文档。

DocumentBuilder常用的属性配置

​

在主模块引入 swagger 模块

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

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

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

10. async function bootstrap() {

12. const app = await NestFactory.create(AppModule);

14. createSwaggerDocument(app);

16. await app.listen(3000);

18. }

20. bootstrap();

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

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

2. @Post()

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

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

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

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

12. create(@Body() createCostRecordDto: CreateCostRecordDto) {

14. return this.costRecordService.create(createCostRecordDto);

16. }

常用的Swagger 装饰器

​

访问接口文档

通过该 URL 来访问接口文档 http://localhost:3000/docs/

​

最后

在这篇文章里，咱们一起走过了如何使用 Swagger 在 Nest.js 项目中构建那些帅气的接口文档。

技术是个不断更新升级的世界，今天学的东西，明天可能就有新玩意儿出炉了。所以，咱们可得保持学习的心态，时刻准备着迎接新知识的挑战。

 

总结：

感谢每一个认真阅读我文章的人！！！

作为一位过来人也是希望大家少走一些弯路，如果你不想再体验一次学习时找不到资料，没人解答问题，坚持几天便放弃的感受的话，在这里我给大家分享一些自动化测试的学习资源，希望能给你前进的路上带来帮助。

软件测试面试文档

我们学习必然是为了找到高薪的工作，下面这些面试题是来自阿里、腾讯、字节等一线互联网大厂最新的面试资料，并且有字节大佬给出了权威的解答，刷完这一套面试资料相信大家都能找到满意的工作。

 

          视频文档获取方式：
这份文档和视频资料，对于想从事【软件测试】的朋友来说应该是最全面最完整的备战仓库，这个仓库也陪伴我走过了最艰难的路程，希望也能帮助到你！以上均可以分享，点下方小卡片即可自行领取。