Spring Boot整合swagger使用教程详解

Swagger的介绍

🔶你可能尝试过写完一个接口后，自己去创建接口文档，或者修改接口后修改接口文档。多了之后，你肯定会发生一个操作，那就是忘记了修改文档或者创建文档（除非你们公司把接口文档和写接口要求得很紧密😓忘记写文档就扣工资？，否则两个分离的工作总是有可能遗漏的）。而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

💡这里先讲添加swagger，也就是先整合进来，至于怎么使用，下面的“场景”中再讲解。

1.添加依赖包：

❗注意，这里的前提是已经导入了spring boot的web包。

 <dependency>
   <groupId>io.springfox</groupId>
   <artifac<div>本文来源gaodai^.ma#com搞#代!码网</div>tId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
  </dependency>
  <dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
  </dependency>

喜欢 (0)赏

[搞代码]

分享 (0)