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

源码地址

微服务开发系列：开篇
微服务开发系列：为什么选择 kotlin
微服务开发系列：为什么用 gradle 构建
微服务开发系列：目录结构，保持整洁的文件环境
微服务开发系列：服务发现，nacos 的小补充
微服务开发系列：怎样在框架中选择开源工具
微服务开发系列：数据库 orm 使用
微服务开发系列：如何打印好日志
微服务开发系列：鉴权
微服务开发系列：认识到序列化的重要性
微服务开发系列：设计一个统一的 http 接口内容形式
微服务开发系列：利用异常特性，把异常纳入框架管理之中
微服务开发系列：利用 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 是可以嵌套使用的。

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