微服务开发系列：利用 knife4j，生成最适合微服务的文档

源码地址

swagger 的优缺点

总结一下优点：

1. 能够快速生成文档
2. 文档能够跟随代码进行发布
3. 在线调试
4. 能够快速分享给其他人，保证高效
5. 使用的人足够多
6. 周边插件足够丰富

这些优点让很多人对 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 是可以嵌套使用的。

这种用法你绝对值得一试，在我开发的过程中，提供了非常的多的帮助，避免了大量的修改接口工作量，同事也减少了沟通上的歧义。