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

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

  2. export const swaggerConfig = new DocumentBuilder()

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

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

  5. .setVersion('1.0')

  6. .build();

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

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

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

  10. };

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

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

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

DocumentBuilder常用的属性配置

在主模块引入 swagger 模块

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

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

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

  4. async function bootstrap() {

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

  6. createSwaggerDocument(app);

  7. await app.listen(3000);

  8. }

  9. bootstrap();

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

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

  1. @Post()

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

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

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

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

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

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

  8. }

常用的Swagger 装饰器

访问接口文档

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

最后

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

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

 

总结:

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

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

软件测试面试文档

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

 

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

  • 11
    点赞
  • 15
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值