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
    
  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();
    
  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;
    }
    
  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);
    }
    }
    

常用 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

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

相关文章
|
4月前
|
人工智能 自然语言处理 JavaScript
通义灵码2.5实战评测:Vue.js贪吃蛇游戏一键生成
通义灵码基于自然语言需求,快速生成完整Vue组件。例如,用Vue 2和JavaScript实现贪吃蛇游戏:包含键盘控制、得分系统、游戏结束判定与Canvas动态渲染。AI生成的代码符合规范,支持响应式数据与事件监听,还能进阶优化(如增加启停按钮、速度随分数提升)。传统需1小时的工作量,使用通义灵码仅10分钟完成,大幅提升开发效率。操作简单:安装插件、输入需求、运行项目即可实现功能。
220 4
 通义灵码2.5实战评测:Vue.js贪吃蛇游戏一键生成
|
5月前
|
存储 JSON API
如何将 Swagger 文档导出为 PDF 文件
你会发现自己可能需要将 Swagger 文档导出为 PDF 或文件,以便于共享和存档。在这篇博文中,我们将指导你完成将 Swagger 文档导出为 PDF 格式的过程。
|
2月前
|
JavaScript 前端开发 算法
流量分发代码实战|学会用JS控制用户访问路径
流量分发工具(Traffic Distributor),又称跳转器或负载均衡器,可通过JavaScript按预设规则将用户随机引导至不同网站,适用于SEO优化、广告投放、A/B测试等场景。本文分享一段不到百行的JS代码,实现智能、隐蔽的流量控制,并附完整示例与算法解析。
62 1
|
5月前
|
前端开发 JavaScript NoSQL
使用 Node.js、Express 和 React 构建强大的 API
本文详细介绍如何使用 Node.js、Express 和 React 构建强大且动态的 API。从开发环境搭建到集成 React 前端,再到利用 APIPost 高效测试 API,适合各水平开发者。内容涵盖 Node.js 运行时、Express 框架与 React 库的基础知识及协同工作方式,还涉及数据库连接和前后端数据交互。通过实际代码示例,助你快速上手并优化应用性能。
|
6月前
|
前端开发 Cloud Native Java
Java||Springboot读取本地目录的文件和文件结构,读取服务器文档目录数据供前端渲染的API实现
博客不应该只有代码和解决方案,重点应该在于给出解决方案的同时分享思维模式,只有思维才能可持续地解决问题,只有思维才是真正值得学习和分享的核心要素。如果这篇博客能给您带来一点帮助,麻烦您点个赞支持一下,还可以收藏起来以备不时之需,有疑问和错误欢迎在评论区指出~
Java||Springboot读取本地目录的文件和文件结构,读取服务器文档目录数据供前端渲染的API实现
|
6月前
|
JavaScript 前端开发 API
JavaScript中通过array.map()实现数据转换、创建派生数组、异步数据流处理、复杂API请求、DOM操作、搜索和过滤等,array.map()的使用详解(附实际应用代码)
array.map()可以用来数据转换、创建派生数组、应用函数、链式调用、异步数据流处理、复杂API请求梳理、提供DOM操作、用来搜索和过滤等,比for好用太多了,主要是写法简单,并且非常直观,并且能提升代码的可读性,也就提升了Long Term代码的可维护性。 只有锻炼思维才能可持续地解决问题,只有思维才是真正值得学习和分享的核心要素。如果这篇博客能给您带来一点帮助,麻烦您点个赞支持一下,还可以收藏起来以备不时之需,有疑问和错误欢迎在评论区指出~
|
6月前
|
监控 JavaScript 前端开发
MutationObserver详解+案例——深入理解 JavaScript 中的 MutationObserver:原理与实战案例
MutationObserver 是一个非常强大的 API,提供了一种高效、灵活的方式来监听和响应 DOM 变化。它解决了传统 DOM 事件监听器的诸多局限性,通过异步、批量的方式处理 DOM 变化,大大提高了性能和效率。在实际开发中,合理使用 MutationObserver 可以帮助我们更好地控制 DOM 操作,提高代码的健壮性和可维护性。 只有锻炼思维才能可持续地解决问题,只有思维才是真正值得学习和分享的核心要素。如果这篇博客能给您带来一点帮助,麻烦您点个赞支持一下,还可以收藏起来以备不时之需,有疑问和错误欢迎在评论区指出~
MutationObserver详解+案例——深入理解 JavaScript 中的 MutationObserver:原理与实战案例
|
7月前
|
存储 机器学习/深度学习 人工智能
如何使用非结构化 API 高效处理文档
手动处理非结构化文档面临格式不一致、数据噪声多和信息检索困难等挑战,导致低效率和合规风险。Unstructured API 通过自动化文档处理,利用AI技术简化分类、归类和异常检测,节省时间和提高准确性。Supametas.AI 作为领先平台,支持多种文件类型(如文本、图片、视频),适用于各行各业,可与Salesforce、Zendesk等工具无缝集成,确保数据流动顺畅并提升工作效率。其强大的功能包括数据摄取、处理技术、检索增强生成、灵活性、可扩展性和集成能力,帮助企业和小公司高效处理大量非结构化数据,实现业务增长和优化工作流程。
354 4
|
8月前
|
JavaScript 前端开发 安全
盘点原生JS中目前最没用的几个功能API
在JavaScript的发展历程中,许多功能与API曾风光无限,但随着技术进步和语言演化,部分功能逐渐被淘汰或被更高效的替代方案取代。例如,`with`语句使代码作用域复杂、可读性差;`void`操作符功能冗余且影响可读性;`eval`函数存在严重安全风险和性能问题;`unescape`和`escape`函数已被`decodeURIComponent`和`encodeURIComponent`取代;`arguments`对象则被ES6的剩余参数语法替代。这些变化体现了JavaScript不断优化的趋势,开发者应紧跟技术步伐,学习新技能,适应新技术环境。
107 10
|
8月前
|
开发框架 数据可视化 .NET
.NET 中管理 Web API 文档的两种方式
.NET 中管理 Web API 文档的两种方式
124 14

热门文章

最新文章