你可能尝试过写完一个接口后，自己去创建接口文档，或者修改接口后修改接口文档。多了之后，你肯定会发生一个操作，那就是忘记了修改文档或者创建文档（除非你们公司把接口文档和写接口要求得很紧密😓忘记写文档就扣工资？，否则两个分离的工作总是有可能遗漏的）。而swagger就是一个在你写接口的时候自动帮你生成接口文档的东西，只要你遵循它的规范并写一些接口的说明注解即可。
优点：
- 自动生成文档，只需要在接口中使用注解进行标注，就能生成对应的接口文档。
- 自动更新文档，由于是动态生成的，所以如果你修改了接口，文档也会自动对应修改（如果你也更新了注解的话）。这样就不会发送我修改了接口，却忘记更新接口文档的情况。
- 支持在线调试，swagger提供了在线调用接口的功能。
缺点
- 不能创建测试用例，所以他暂时不能帮你处理完所有的事情。他只能提供一个简单的在线调试，如果你想存储你的测试用例，可以使用Postman或者YAPI这样支持创建测试用户的功能。
- 要遵循一些规范，它不是任意规范的。比如说，你可能会返回一个json数据，而这个数据可能是一个Map格式的，那么我们此时不能标注这个Map格式的返回数据的每个字段的说明，而如果它是一个实体类的话，我们可以通过标注类的属性来给返回字段加说明。也比如说，对于swagger，不推荐在使用GET方式提交数据的时候还使用Body，仅推荐使用query参数、header参数或者路径参数，当然了这个限制只适用于在线调试。
- 没有接口文档更新管理，虽然一个接口更新之后，可能不会关心旧版的接口信息，但你“可能”想看看旧版的接口信息，例如有些灰度更新发布的时候可能还会关心旧版的接口。那么此时只能由后端去看看有没有注释留下了，所以可以考虑接口文档大更新的时候注释旧版的，然后写下新版的。【当然这个问题可以通过导出接口文档来对比。】
- 虽然现在Java的实体类中有不少模型，po,dto,vo等，模型的区分是为了屏蔽一些多余参数，比如一个用户登录的时候只需要username,password，但查权限的时候需要连接上权限表的信息，而如果上述两个操作都是使用了User这个实体的话，在文档中就会自动生成了多余的信息，这就要求了你基于模型来创建多个实体类，比如登录的时候一个LoginForm，需要用户-权限等信息的时候才使用User类。（当然了，这个问题等你会swagger之后你就大概就会怎么规避这个问题了。）
😓上面的缺点好像写的有点多，你可能会觉得swagger这个坑有点大。但其实主要是规范问题，而规范问题有时候又会提高你的代码规范性，这个就见仁见智了，你以前可能什么接口的参数都使用一个类，而现在swagger要求你分开后，某种层次上提高了你的代码规范性。
🔶注：以下代码示例基于Spring Boot。完整代码可以参考：swagger-demo
💡这里先讲添加swagger，也就是先整合进来，至于怎么使用，下面的“场景”中再讲解。
❗注意，这里的前提是已经导入了spring boot的web包。
要使用swagger，我们必须对swagger进行配置，我们需要创建一个swagger的配置类，比如可以命名为
如果需要配置多个组的话，就需要配置多个 方法
运行我们的Spring Boot项目，（我默认是8080端口，如果你不一样，请注意修改后续的url），访问
然后你就可以看到一个如下的界面，由于我们暂时没有配置接口数据，所以下面显示
💡下面我们将介绍如何定义接口，以及在swagger UI界面中的内容。
和
🔵你也可以理解成基于tags来分组，就好像一些文章里面的标签一样，使用标签来分类。
🔵如果这个Controller下（接口组）下面没有接口，那么在swagger ui中是不会显示的，如果有的话就会这样显示：
使用了来标注一个Controller之后，如果下面有接口，那么就会默认生成文档，但没有我们自定义的说明：
我们可以使用来描述接口，比如：
常用配置项：
- value：可以当作是接口的简称
- notes：接口的描述
- tags：可以额外定义接口组，比如这个接口外层已经有@Api(tags = “用户管理”)，将接口划分到了“用户管理”中，但你可以额外的使用tags，例如tags = "角色管理"让角色管理中也有这个接口文档。
场景一：请求参数是实体类。
此时我们需要使用来标注实体类，然后在接口中定义入参为实体类即可：
- @ApiModel：用来标类
- 常用配置项：
- value：实体类简称
- description：实体类说明
- 常用配置项：
- @ApiModelProperty：用来描述类的字段的意义。
- 常用配置项：
- value：字段说明
- example：设置请求示例（Example Value）的默认值，如果不配置，当字段为string的时候，此时请求示例中默认值为"".
- name：用新的字段名来替代旧的字段名。
- allowableValues：限制值得范围，例如{1,2,3}代表只能取这三个值；[1,5]代表取1到5的值；(1,5)代表1到5的值，不包括1和5；还可以使用infinity或-infinity来无限值，比如[1, infinity]代表最小值为1，最大值无穷大。
- required：标记字段是否必填，默认是false,
- hidden：用来隐藏字段，默认是false，如果要隐藏需要使用true，因为字段默认都会显示，就算没有。
- 常用配置项：
定义成入参：
效果：
场景二：请求参数是非实体类。
（再说一次：对于GET方式，swagger不推荐使用body方式来传递数据，所以虽然Spring MVC可以自动封装参数，但对于GET请求还是不要使用form-data，json等方式传递参数，除非你使用Postman来测试接口，swagger在线测试是不支持这个操作的）
对于非实体类参数，可以使用和来声明请求参数。
用在方法头上，@定义在里面，一个对应一个参数。
常用配置项：
- name：用来定义参数的名字，也就是字段的名字,可以与接口的入参名对应。如果不对应，也会生成，所以可以用来定义额外参数！
- value：用来描述参数
- required：用来标注参数是否必填
- paramType有path,query,body,form,header等方式，但对于对于非实体类参数的时候，常用的只有path,query,header；body和form是不常用的。body不适用于多个零散参数的情况，只适用于json对象等情况。
【如果你的接口是,的时候可能不能使用swagger页面API调试，但可以在后面讲到基于BootstrapUI的swagger增强中调试，基于BootstrapUI的swagger支持指定或】
示例一：声明入参是URL参数
示例二：声明入参是URL路径参数
示例三：声明入参是header参数
示例四：声明文件上传参数
响应是非实体类：
你可能会觉得现在这个UI不是很好看，现在有一些第三方提供了一些Swagger UI增强，比较流行的是，我们这里以为例。
1.添加依赖包：
2.在swagger配置类中增加注解:
3.访问API：，即可预览到基于bootstarp的Swagger UI界面。
1.🤔界面好看了一点
2.上面说过了，基于BootstrapUI的swagger支持指定或：
3.支持复制单个API文档和导出全部API文档：
在Spring Boot整合Spring Security和Swagger的时候，需要配置拦截的路径和放行的路径，注意是放行以下几个路径。
在swagger中只支持了简单的调试，但对于一些接口，我们测试的时候可能需要把token信息写到header中，目前好像没看到可以自定义加请求头的地方？
💡方法一：如果你使用了Swagger BootstrapUI，那么你可以在“文档管理”中增加全局参数，这包括了添加header参数。
💡方法二：在swagger配置类中增加全局参数配置：
💡方法三：使用来额外标注一个请求头参数，例如：
1.如果你整合了权限管理，可以给swagger加上权限管理，要求访问swagger页面输入用户名和密码，这些是spring security和shiro的事了，这里不讲。
2.如果你仅仅是不想在正式环境中可以访问，可以在正式环境中关闭Swagger自动配置，这就不会有swagger页面了。使用注解来限制只在dev或者test下启用Swagger自动配置。
然后在Spring Boot配置文件中修改当前，重启之后，此时无法访问
参考：Springfox 3.0.0（包含springfox-swagger2-3.0.0）即OpenAPI 3的发布与系统集成
官网地址：https://swagger.io/resources/open-api/
1、说明
是在上做了大版本升级，使用方式和Swagger2大体一致，只是需要注意区别配置地方，Swagger3使用相关依赖版本如下：
- 需要Java 8
- 需要Spring5.x（未在早期版本中测试）
- 需要SpringBoot 2.2+（未在早期版本中测试）
2、区别
- 1.导入Maven坐标
优化：openapi3依赖添加，现在非常方便，不像以往2.9.2版本需要好几个依赖，现在只需添加一个
io.springfox springfox-boot-starter 3.0.0 - 2.配置
推荐配置文件和代码分离
注解的更改：由之前的@Swagger2更改为@EnableOpenApi
Docket构造函数中的DocumentationType指向更改：由之前的 更改为
对于扫描路径部分可以自行选择（当项目人多的时候可以自由扩展，人少就自行安排）
paths(PathSelectors.regex(“asds”)
.or(PathSelectors.regex(“adsd”))
.or(…)
)
此外还具备swagger进行授权配置，在开发环境的基础上进一步封装
版权声明：
本文来源网络，所有图片文章版权属于原作者，如有侵权，联系删除。
本文网址：https://www.mushiming.com/mjsbk/1769.html