做淘宝详情的网站,昆明网站建设在河科技,学生html个人网页模板,网站js时间代码什么是 Swagger ?
Swagger 是一组围绕 OpenAPI 规范构建的开源工具#xff0c;可以帮助您设计、构建、记录和使用 REST API。主要的 Swagger 工具 包括#xff1a;
Swagger Editor#xff1a;基于浏览器的编辑器#xff0c;您可以在其中编写 OpenAPI 定义Swagger UI可以帮助您设计、构建、记录和使用 REST API。主要的 Swagger 工具 包括
Swagger Editor基于浏览器的编辑器您可以在其中编写 OpenAPI 定义Swagger UI将 OpenAPI 定义呈现为交互式文档Swagger Codegen从 OpenAPI 定义中生成服务器存根和客户端库Swagger Editor Nextbeta基于浏览器的编辑器您可以在其中编写和查看 OpenAPI 和 AsyncAPI 定义Swagger Core用于创建、使用和处理 OpenAPI 定义的 Java 相关库Swagger Parser用于解析 OpenAPI 定义的独立库Swagger APIDom提供了一个单一的、统一的结构用于跨各种描述语言和序列化格式描述 API
Nest 集成 Swagger
安装依赖
pnpm add nestjs/swagger swagger-ui-express在 main.ts 文件中定义并初始化 SwaggerModule 类 import { NestFactory } from nestjs/core;import { DocumentBuilder, SwaggerModule } from nestjs/swagger;import { AppModule } from ./app.module;async function bootstrap() {const app await NestFactory.create(AppModule);// 构建swagger文档const options new DocumentBuilder().setTitle(vue3-admin).setDescription(Background system based on Nest.js Vue3 full stack development).setVersion(1.0).build();const document SwaggerModule.createDocument(app, options);SwaggerModule.setup(docs, app, document);await app.listen(3000);}bootstrap();启动服务访问http://localhost:3000/docs你会看到 Swagger 页面
DocumentBuilder 属性
方法描述setTitle文档标题setDescription文档描述setVersion文档版本setTermsOfService文档服务条款setContact文档联系信息setLicense文档许可证信息addServer文档服务地址setExternalDoc文档外部链接setBasePath设置文档基础路径addTag添加文档标签addExtension添加扩展addSecurity添加安全方案addGlobalParameters添加全局参数addSecurityRequirements添加安全需求addBearerAuth添加 Bearer Token 认证addOAuth2添加 OAuth2 认证addApiKey添加 ApiKeyaddBasicAuth添加基础认证addCookieAuth添加 Cookie 认证build构建服务
在 Nest 中使用
在 DTO(响应数据传输对象) 文件中使用装饰器 import { ApiProperty } from nestjs/swagger;import { IsNumberString, IsOptional, IsUUID } from class-validator;export class PostParamsDto {ApiProperty({type: String,description: 岗位名称,required: false,default: 前端工程师,})name?: string;ApiProperty({type: String,description: 所属组织,default: f45cd48b-e703-49db-91be-ae7f594e73e0,required: false,})IsOptional()IsUUID(all, { message: orgId 参数不正确 })orgId?: string;ApiProperty({type: Number,description: 开始日期,default: 1721145600000,required: false,})IsOptional()IsNumberString({}, { message: 开始日期必须是时间戳格式 })startTime?: number;ApiProperty({type: Number,description: 结束日期,default: 1721318399999,required: false,})IsOptional()IsNumberString({}, { message: 结束日期必须是时间戳格式 })endTime?: number;}在 Controller 控制器 中使用装饰器
import { Controller, Get, Query } from nestjs/common;
import { ApiOkResponse, ApiOperation, ApiTags } from nestjs/swagger; // swagger 接口文档import { PostParamsDto } from ./dto/params-post.dto;
import { ResponsePostDto } from ./dto/response-post.dto;
import { PostManageService } from ./post-manage.service;ApiTags(智能行政-岗位管理)
Controller(post-manage)
export class PostManageController {constructor(private readonly postManageService: PostManageService) { }/*** description: 查询岗位列表*/Get()ApiOkResponse({ type: ResponsePostDto })ApiOperation({ summary: 获取岗位管理列表 })findAll(Query() params: PostParamsDto) {return this.postManageService.findAll(params);}
}常用 Swagger 装饰器
装饰器描述ApiTags为控制器或方法添加标签用于组织 Swagger UI 文档ApiOperation为控制器方法添加操作描述包括摘要和详细描述ApiParam描述路径参数、请求参数或响应参数包括名称、类型、描述等ApiBody指定请求体的 DTO 类型用于描述请求体的结构ApiResponse描述 API 的响应包括状态码、描述等ApiBearerAuth指定请求需要携带 Bearer Token用于身份验证ApiProperty为 DTO 类型的属性添加元数据如描述、默认值等ApiQuery描述查询参数包括名称、类型、描述等ApiHeader描述请求头信息包括名称、类型、描述等ApiExcludeEndpoint标记一个控制器方法不在 Swagger UI 中显示
效果图 总结
在 Nest 中集成 Swagger 文档可以帮助开发者自动生成和维护 API 文档Swagger 的集成提供了在线生成、自动生成、可操作数据库等优点规范了 API 的标准化和一致性后期还可以把 Swagger 文档导入到其他平台例如 ApiFox
不足之处就是会增加开发者的工作量每一个接口都需要保持注释和装饰器的准确性和完整性仍然需要一定的维护工作。
