什么是Swagger，一篇带你入门
来源：blog.csdn.net 编辑：xjh 2025-03-12
一、前言
在前后端分离开发的过程中，前端和后端需要进行api对接进行交互，就需要一个api规范文档，方便前后端的交互，但api文档不能根据代码的变化发生实时动态的改变，这样后端修改了接口，前端不能及时获取最新的接口，导致调用出错，需要手动维护api文档，加大了开发的工作量和困难，而Swagger的出现就是为了解决这一系列的问题。
二、Swagger的概述
Swagger 是一个 RESTful 接口文档的规范和工具集，它的目标是统一 RESTful 接口文档的格式和规范。在开发过程中，接口文档是非常重要的一环，它不仅方便开发者查看和理解接口的功能和参数，还能帮助前后端开发协同工作，提高开发效率。在 Spring Boot 中，我们可以通过集成 Swagger 来实现接口文档的自动生成。Swagger 通过注解来描述接口，然后根据这些注解自动生成接口文档。
Swagger是一套基于OpenAPI规范构建的开源工具，使用RestApi
1、代码变，文档变
2、跨语言，支持多种语言
3、Swagger-ui 呈现出来的是一份可交互式的API文档，可以直接在文档页面尝试API的调用
4、可以将文档规范导入相关工具（postman、soapui），这些工具将会为我们自动地创建自动化测试
补充：
RestApi格式是根据请求的方式决定本次请求的一个操作，譬如：get-->读，post-->写（增、删、改），put-->修改，delete-->删除
OpenApi与语言无关，只是一种规范，可以使用yaml和json格式进行编写，这样更利于我们和机器进行阅读。
swagger主要包含了以下三个部分：
swagger editor：基于浏览器的编辑器，我们可以使用它编写我们OpenApi规范(yaml或者json配置）
Swagger UI：他会将我们编写的OpenApi规范呈现为交互式的API文档，后文我将使用浏览器来查看并且操作我们的RestApi
Swagger Codegen：它可以通过OpenApi规范定义的任何API生成服务器存根和客户端SDK来简化构建过程
使用Swagger就是把相关信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码
三、Springfox概述
使用Swagger时如果碰见版本更新迭代时，只需要更改Swagger的描述文件即可，但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件（yml或json文件）也是一定的工作负担，久而久之就直接修改代码，而不去修改描述文件了，这样基于描述文件生成接口文档也失去了意义。
Marty Pitt编写了一个基于spring的组件swagger-springmvc,Spring-fox就是根据这个组件发展而来的全新项目;
Spring-fox是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可，而不需要跟随修改描述文件(yml或json文件）;
Spring-fox利用自身AOP特性，把swagger集成进来，底层还是Swagger，但是使用起来却方便很多，所以在实际开发中，都是直接使用Spring-fox。
四、Swagger的使用
1、新建springboot项目
2、导入相关依赖
3、启动类中添加@EnableSwagger2注解
@enableSwagger2：是springfox提供的一个注解，代表swagger2相关技术开启,会扫描当前类所在包，以及子包中所有的类型中的注解，做swagger文档的定值。
4、编写一个简单api接口
在编写接口时，我们需要使用 Swagger 的注解来描述接口信息。常用的注解包括：
@Api：用于描述接口的类或接口
@ApiOperation：用于描述接口的方法
@ApiParam：用于描述接口的参数
@ApiModel：用于描述数据模型
@ApiModelProperty：用于描述数据模型的属性
5、启动项目，并在浏览器输入http://localhost:8080/swagger-ui.html进行swagger-ui界面访问。
6、开发和测试环境中开启swagger，其他环境不开启，需要做相应配置。
五、Swagger常用注解
Swagger注解主要是用来给Swagger生成的接口文档说明用的，具体注解使用详见参考文档。
六、总结
我们可以通过Swagger给一些比较难理解的属性或接口，增加注释信息。
接口文档实时更新。
可以在线测试。
在正式发布的时候，关闭Swagger，出于安全考虑，而且节省内存。
来源：
https://blog.csdn.net/UniqueMiracle/article/details/143630243
https://blog.csdn.net/hh867308122/article/details/130094120