swagger 的优缺点
总结一下长处：
- 可能疾速生成文档
- 文档可能追随代码进行公布
- 在线调试
- 可能疾速分享给其他人，保障高效
- 应用的人足够多
- 周边插件足够丰盛
这些长处让很多人对 swagger 非常科学，包含我本人，然而它的存在并不是那么完满，在我应用过程中，我认为最大的问题就乱。
上图就是一个简单一些的办法，两者正文的比拟，很显著 swagger 更显得啰嗦很多。
swagger 尽管肯定水平上可能起到正文加上文档两者合并的作用，然而副作用就是，与代码纠缠在一起。
这也就是说，swagger 对代码的侵入水平过大。
因而，倡议深度应用 swagger 较多的开发人员，谨慎把握其中的复杂度，尽量做到精简高效，保障代码的可读性。
相比拟来说，apigcc 是一款利用 javadoc 自身的正文能力提供的文档生成工具，然而毛病更为显著，swagger 的长处它基本上都没有。
所以目前来说，出了 swagger 以外，还真找不到更加优良的文档生成工具。
swagger 在 spring cloud gateway 中应用
swagger 在微服务架构中遇到的问题就是，拜访不同的模块，须要通过不同的地址，没有通过网关对立治理起来。
对此能够应用，knife4j 能够解决这个问题。
配置好了之后，在零碎中，能够间接通过 http://ip:port/doc.html 间接拜访各个系统的文档。
要害类在 gateway:cn.gateway.core.swagger.SwaggerHandler 和 gateway:cn.gateway.core.swagger.SwaggerResourceConfig 中，这两个类是固定的。
其余模块通过依赖 framework:cn.framework.config.swagger.SwaggerConfiguration 取得 swagger 的能力，该类能够通过判断是否依赖了 swagger 的模块，来决定是否进行 swagger 的配置，该类可能主动判断包门路，扫描所有的 swagger 接口，无需再进行额定的配置。
最大化利用 swagger
相当一部分开发人员，应用 swagger 时，都只留了一个对于接口的形容，然而没有利用起来它对于参数形容的能力。
对此，倡议更多的应用 java 对象传递参数，而后在对象成员字段上应用注解 ApiModelProperty，这样可能帮忙你更好的向前端形容你须要什么参数以及参数的含意。
ApiModelProperty 是能够嵌套应用的。
这种用法你相对值得一试，在我开发的过程中，提供了十分的多的帮忙，防止了大量的批改接口工作量，共事也缩小了沟通上的歧义。