当前位置: 首页 > news >正文

Swagger详解API 文档

Swagger 是一套基于 OpenAPI 规范构建的开源工具,可以帮助我们设计、构建、记录以及使用 Rest API。
Swagger 主要包含了以下三个部分:
Swagger Editor:基于浏览器的编辑器,我们可以使用它编写我们 OpenAPI 规范。
Swagger UI:它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档。
Swagger Codegen:它可以通过为 OpenAPI规范定义的任何 API 生成服务器存根和客户端 SDK 来简化
构建过程。
2、为什么要使用 Swagger
在前后端分离开发以后,维持一份及时更新且完整的 Rest API 文档,能够极大的提高的开发效率。传统意
义上的文档都是后端开发人员手动编写的,一般是以Doc或者是md等形式离线传播。而在开发阶段,接口修改
非常频繁,就很难保证文档更新的及时性,久而久之就失去了参考意义,反而还会加大团建之间的沟通成本。
而 Swagger 给我们提供了一个全新的维护 API 文档的方式,只要项目发布,就能够自动更新,而且可以
同步到线上,使用者只需要记住一个固定的网址,实时刷新就能访问到最新版本的API文档了。下面我总结一下
Swagger的主要优点:
1)代码变,文档变。只需要少量的注解,Swagger 就可以根据代码自动生成 API 文档,很好的保证了文档的
时效性。
2)跨语言性,支持 40 多种语言。
3)提供交互式的UI,我们可以直接在文档页面调试 API,省去了准备复杂的调试参数的过程。
4)还可以将文档导入到自动化测试工具中,快速生成测试报告。
3、Swagger工作流程
Swagger接口生成工作流程:
1、系统启动时,扫描Swagger的配置类
2、在此类中指定来要扫描的包路径,找到在此包下及子包下标记@RestController注解的Controller类。还可
以通过以下这些注解来灵活配置一些参数。
比如:配置发送错误返回的信息 @ApiError ,配置一个或者多个请求参数,@ApiImplicitParam、@ApiImplicitParams等等。
3、根据Controller类中的Swagger注解生成接口文档,启动项目,访问项目虚拟路径/swagger-ui,查看生成
的文档内容。

Swagger 详解

Swagger 是一套用于 设计、构建、文档化和消费 RESTful API 的开源工具集,现已成为 OpenAPI 规范(OAS)的核心实现之一。它可以帮助开发者快速生成 API 文档、进行接口测试,并支持客户端代码自动生成。


1. Swagger 核心组件

(1) OpenAPI 规范(OAS)

  • 定义 RESTful API 的标准格式(YAML/JSON)。
  • 描述 API 的路径(Paths)、请求方法(HTTP Methods)、参数(Parameters)、响应(Responses)等。

(2) Swagger 工具生态

工具作用
Swagger Editor在线编辑器,用于编写和预览 OpenAPI 规范文档(YAML/JSON)。
Swagger UI可视化 API 文档,支持在线测试接口。
Swagger Codegen根据 API 规范生成客户端代码(如 Java、Python、TypeScript)。
Swagger Hub企业级 API 设计、协作和托管平台(需付费)。

2. Spring Boot 集成 Swagger(SpringDoc OpenAPI)

由于 Swagger 2.x 已逐渐被 SpringDoc OpenAPI 3.x 取代(基于 OpenAPI 3.0),以下以 springdoc-openapi 为例:

(1) 添加依赖

<!-- SpringDoc OpenAPI (替代Swagger2) -->
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.5.0</version>
</dependency>

(2) 配置 Swagger UI

默认访问地址:http://localhost:8080/swagger-ui.html
可通过 application.yml 自定义:

springdoc:swagger-ui:path: /api-docs         # 修改Swagger UI路径tags-sorter: alpha      # 按字母排序标签operations-sorter: alpha # 按字母排序接口api-docs:path: /v3/api-docs      # OpenAPI JSON描述文件路径

(3) 常用注解

注解作用示例
@Tag定义API分组(替代@Api@Tag(name = "用户管理", description = "用户相关接口")
@Operation描述接口方法(替代@ApiOperation@Operation(summary = "创建用户", description = "根据User对象创建用户")
@Parameter描述请求参数@Parameter(name = "id", description = "用户ID", required = true)
@Schema定义模型属性(替代@ApiModelProperty@Schema(description = "用户名", example = "张三")
@Hidden隐藏接口/字段@Hidden(不显示在Swagger UI中)

3. 代码示例

(1) Controller 示例

@RestController
@Tag(name = "用户管理", description = "用户相关API")
@RequestMapping("/api/users")
public class UserController {@Operation(summary = "获取用户列表", description = "返回所有用户")@GetMappingpublic List<User> getUsers() {return userService.list();}@Operation(summary = "创建用户")@PostMappingpublic User createUser(@RequestBody @Valid User user) {return userService.save(user);}@Operation(summary = "根据ID查询用户")@Parameter(name = "id", description = "用户ID", required = true)@GetMapping("/{id}")public User getUserById(@PathVariable Long id) {return userService.getById(id);}
}

(2) DTO 模型示例

@Schema(description = "用户实体")
public class User {@Schema(description = "用户ID", example = "1")private Long id;@Schema(description = "用户名", example = "张三")private String name;@Schema(description = "邮箱", example = "user@example.com")private String email;// Getters & Setters
}

4. Swagger UI 功能

访问 http://localhost:8080/swagger-ui.html 后:

  • 接口列表:按分组展示所有API。
  • 在线测试:直接填写参数发起请求。
  • 模型定义:查看请求/响应的数据结构。
  • 下载OpenAPI JSON:通过 /v3/api-docs 获取标准描述文件。

5. 高级配置

(1) 安全认证(JWT/OAuth2)

@Configuration
public class SwaggerConfig {@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().components(new Components().addSecuritySchemes("BearerAuth", new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT"))).info(new Info().title("API文档").version("1.0"));}
}

(2) 分组显示多个模块

@Bean
public GroupedOpenApi publicApi() {return GroupedOpenApi.builder().group("user").pathsToMatch("/api/users/**").build();
}

(3) 排除某些接口

springdoc:packages-to-exclude: com.example.internal.*

6. 常见问题

Q1: Swagger UI 不显示?

  • 检查依赖是否正确引入。
  • 确认路径是否被拦截(如Spring Security需放行/swagger-ui/**)。

Q2: 如何隐藏某些接口?

  • 在方法上添加 @Hidden 注解。
  • 使用 @Operation(hidden = true)

Q3: 如何生成离线文档?

  • 访问 /v3/api-docs 下载JSON文件,导入 Swagger Editor 生成HTML/PDF。

总结

  • Swagger UI + OpenAPI 3.0 是当前主流API文档工具。
  • SpringDoc 替代了旧的 springfox-swagger
  • 通过注解(@Tag@Operation)定义接口细节。
  • 支持在线测试、代码生成和权限集成。

适用于团队协作、前后端联调及自动化测试场景。

http://www.lryc.cn/news/599624.html

相关文章:

  • C#(基本语法)
  • C语言中奇技淫巧04-仅对指定函数启用编译优化
  • 恋爱时间倒计时网页设计与实现方案
  • C#观察者模式示例代码
  • Idefics2:构建视觉-语言模型时,什么是重要的
  • ‌通向数字孪生的大门:掌握RVT到3DTiles的关键转换流程
  • 【NLP舆情分析】基于python微博舆情分析可视化系统(flask+pandas+echarts) 视频教程 - 主页-评论用户时间占比环形饼状图实现
  • 经验累积分布函数VS累积分布函数
  • Vue nextTick
  • 基于多模型AI训练与验证系统开发
  • 移动端设备能部署的llm
  • MC_GearInPos电子齿轮
  • Pytest tmp_path 实战指南:测试中的临时目录管理
  • 基于单片机的数字电压表设计
  • MyBatis-Plus 指南
  • 光耦合器:新能源世界的“绿色信使“
  • 全面解析MySQL(3)——CRUD进阶与数据库约束:构建健壮数据系统的基石
  • Krpano 工具如何调节全景图片切割之后的分辨率
  • 代码随想录算法训练营第三十一天
  • 卡尔曼滤波器噪声方差设置对性能影响的仿真研究
  • MATLAB 设置默认启动路径为上次关闭路径的方法
  • 【优选算法】链表
  • 从 SQL Server 到 KingbaseES V9R4C12,一次“无痛”迁移与深度兼容体验实录
  • UG创建的实体橘黄色实体怎么改颜色?
  • 每日算法-数组合并
  • [RPA] Excel中的字典处理
  • ubuntu22.04.4锁定内核应对海光服务器升级内核无法启动问题
  • CPU(中央处理器)和GPU(图形处理器)的区别
  • 在线事务型的业务、实时分析类业务、离线处理类型的业务
  • 如何提高微信小程序的应用速度