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 装饰器
访问接口文档
通过该 URL 来访问接口文档 http://localhost:3000/docs/
最后
在这篇文章里,咱们一起走过了如何使用 Swagger 在 Nest.js 项目中构建那些帅气的接口文档。
技术是个不断更新升级的世界,今天学的东西,明天可能就有新玩意儿出炉了。所以,咱们可得保持学习的心态,时刻准备着迎接新知识的挑战。
总结:
感谢每一个认真阅读我文章的人!!!
作为一位过来人也是希望大家少走一些弯路,如果你不想再体验一次学习时找不到资料,没人解答问题,坚持几天便放弃的感受的话,在这里我给大家分享一些自动化测试的学习资源,希望能给你前进的路上带来帮助。
软件测试面试文档
我们学习必然是为了找到高薪的工作,下面这些面试题是来自阿里、腾讯、字节等一线互联网大厂最新的面试资料,并且有字节大佬给出了权威的解答,刷完这一套面试资料相信大家都能找到满意的工作。
视频文档获取方式:
这份文档和视频资料,对于想从事【软件测试】的朋友来说应该是最全面最完整的备战仓库,这个仓库也陪伴我走过了最艰难的路程,希望也能帮助到你!以上均可以分享,点下方小卡片即可自行领取。