Nest.js 实战 (三):使用 Swagger 优雅地生成 API 文档

简介: 这篇文章介绍了Swagger,它是一组开源工具,围绕OpenAPI规范帮助设计、构建、记录和使用RESTAPI。文章主要讨论了Swagger的主要工具,包括SwaggerEditor、SwaggerUI、SwaggerCodegen等。然后介绍了如何在Nest框架中集成Swagger,展示了安装依赖、定义DTO和控制器等步骤,以及如何使用Swagger装饰器。文章最后总结说,集成Swagger文档可以自动生成和维护API文档,规范API标准化和一致性,但会增加开发者工作量,需要保持注释和装饰器的准确性。

什么是 Swagger ?

Swagger 是一组围绕 OpenAPI 规范构建的开源工具,可以帮助您设计、构建、记录和使用 REST API。主要的 Swagger 工具 包括:

Nest 集成 Swagger

  1. 安装依赖
    pnpm add @nestjs/swagger swagger-ui-express
    
    AI 代码解读
  2. 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();
    
    AI 代码解读
  3. 启动服务,访问http://localhost:3000/docs,你会看到 Swagger 页面:
    ve5yt9s0se80a5cityx55zpj01rtdcv1.png

DocumentBuilder 属性

方法 描述
setTitle 文档标题
setDescription 文档描述
setVersion 文档版本
setTermsOfService 文档服务条款
setContact 文档联系信息
setLicense 文档许可证信息
addServer 文档服务地址
setExternalDoc 文档外部链接
setBasePath 设置文档基础路径
addTag 添加文档标签
addExtension 添加扩展
addSecurity 添加安全方案
addGlobalParameters 添加全局参数
addSecurityRequirements 添加安全需求
addBearerAuth 添加 Bearer Token 认证
addOAuth2 添加 OAuth2 认证
addApiKey 添加 ApiKey
addBasicAuth 添加基础认证
addCookieAuth 添加 Cookie 认证
build 构建服务

在 Nest 中使用

  1. 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;
    }
    
    AI 代码解读
  2. 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);
    }
    }
    
    AI 代码解读

常用 Swagger 装饰器

装饰器 描述
@ApiTags 为控制器或方法添加标签,用于组织 Swagger UI 文档
@ApiOperation 为控制器方法添加操作描述,包括摘要和详细描述
@ApiParam 描述路径参数、请求参数或响应参数,包括名称、类型、描述等
@ApiBody 指定请求体的 DTO 类型,用于描述请求体的结构
@ApiResponse 描述 API 的响应,包括状态码、描述等
@ApiBearerAuth 指定请求需要携带 Bearer Token,用于身份验证
@ApiProperty 为 DTO 类型的属性添加元数据,如描述、默认值等
@ApiQuery 描述查询参数,包括名称、类型、描述等
@ApiHeader 描述请求头信息,包括名称、类型、描述等
@ApiExcludeEndpoint 标记一个控制器方法不在 Swagger UI 中显示

效果图

cz9r4j5zgochx1r1xc2g6og0yx5mlv8d.png

总结

Nest 中集成 Swagger 文档可以帮助开发者自动生成和维护 API 文档,Swagger 的集成提供了在线生成、‌自动生成、‌可操作数据库等优点,规范了 API 的标准化和一致性,后期还可以把 Swagger 文档导入到其他平台,例如 ApiFox
xjt59k8vturpenfaamoxy89eqcwkajpk.png

不足之处就是会增加开发者的工作量,每一个接口都需要保持注释和装饰器的准确性和完整性,仍然需要一定的维护工作。

目录
打赏
0
0
0
0
54
分享
相关文章
API 资源详解:从概念到实战的完整指南
本文深入解析了 API 资源的概念、特征与设计原则,涵盖 RESTful 规范、资源分类、层级结构及实际应用示例。内容还包括版本管理、安全策略与性能优化技巧,帮助开发者构建高效、可维护的 API 系统。
7天精通电商API:从接入到运维的完整实战手册
本文全面解析电商API接口技术,从基础概念到高阶应用,涵盖商品、订单、支付与营销等核心模块,并深入探讨性能优化、安全防护与智能化发展方向,助你掌握驱动数字商业的核心技术。
详解手机状态查询API实战指南
手机状态查询API是一款高效接口,可实时识别手机号状态(实号、空号、风险号等),帮助企业筛选有效号码,提升业务触达率与客户体验。
61 0
亚马逊SP-API开发实战:商品数据获取与操作
本文介绍了亚马逊SP-API接入流程,包括开发者注册、OAuth2.0认证示例及核心商品接口的使用。涵盖商品信息查询、批量查询、限流规则与错误处理,并提供最佳实践建议,如使用AWS Lambda与SQS实现高效数据同步。
亚马逊SP-API开发实战:商品数据获取与操作
1688平台开放接口实战:如何通过API获取店铺所有商品数据(Python示列)
本文介绍如何通过1688开放平台API接口获取店铺所有商品,涵盖准备工作、接口调用及Python代码实现,适用于商品同步与数据监控场景。
流量分发代码实战|学会用JS控制用户访问路径
流量分发工具(Traffic Distributor),又称跳转器或负载均衡器,可通过JavaScript按预设规则将用户随机引导至不同网站,适用于SEO优化、广告投放、A/B测试等场景。本文分享一段不到百行的JS代码,实现智能、隐蔽的流量控制,并附完整示例与算法解析。
36 1
|
17天前
|
汇率查询API实战指南:通过Python调用获取多国汇率信息
本文介绍如何通过 Python 快速集成多币种汇率查询接口,实现实时获取全球主要货币汇率数据。适用于跨境电商价格换算、国际贸易结算等场景,帮助提升用户体验并规避汇率波动风险。
168 0
汇率查询API实战指南:通过Python调用获取多国汇率信息
电商数据API开发实战经验分享(实操)
本文分享了一位电商开发者在API实战中的经验总结,涵盖签名生成、数据解析、缓存策略及测试方案,附完整代码示例,助你避开开发“深坑”。
|
4月前
|
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的使用
本文详细介绍了Swagger2的使用方法,包括在Spring Boot项目中的配置与应用。重点讲解了Swagger2中常用的注解,如实体类上的`@ApiModel`和`@ApiModelProperty`,Controller类上的`@Api`、`@ApiOperation`以及参数上的`@ApiParam`等。通过示例代码展示了如何为实体类和接口添加注解,并在页面上生成在线接口文档,实现接口测试。最后总结了Swagger的优势及其在项目开发中的重要性,提供了课程源代码下载链接供学习参考。
127 0
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的使用
|
4月前
|
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的配置
本文介绍了在Spring Boot中配置Swagger2的方法。通过创建一个配置类,添加`@Configuration`和`@EnableSwagger2`注解,使用Docket对象定义API文档的详细信息,包括标题、描述、版本和包路径等。配置完成后,访问`localhost:8080/swagger-ui.html`即可查看接口文档。文中还提示了可能因浏览器缓存导致的问题及解决方法。
143 0
微服务——SpringBoot使用归纳——Spring Boot集成 Swagger2 展现在线接口文档——Swagger2 的配置

热门文章

最新文章

AI助理

你好,我是AI助理

可以解答问题、推荐解决方案等

登录插画

登录以查看您的控制台资源

管理云资源
状态一览
快捷访问