乐趣区

关于微服务:微服务开发系列利用利用-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.SwaggerHandlergateway:cn.gateway.core.swagger.SwaggerResourceConfig 中,这两个类是固定的。

其余模块通过依赖 framework:cn.framework.config.swagger.SwaggerConfiguration 取得 swagger 的能力,该类能够通过判断是否依赖了 swagger 的模块,来决定是否进行 swagger 的配置,该类可能主动判断包门路,扫描所有的 swagger 接口,无需再进行额定的配置。

最大化利用 swagger

相当一部分开发人员,应用 swagger 时,都只留了一个对于接口的形容,然而没有利用起来它对于参数形容的能力。

对此,倡议更多的应用 java 对象传递参数,而后在对象成员字段上应用注解 ApiModelProperty,这样可能帮忙你更好的向前端形容你须要什么参数以及参数的含意。

ApiModelProperty 是能够嵌套应用的。

这种用法你相对值得一试,在我开发的过程中,提供了十分的多的帮忙,防止了大量的批改接口工作量,共事也缩小了沟通上的歧义。

退出移动版