在过去,尤其是 java web 服务端开发者,绝大多数都采用 swagger 来生成项目的接口文档。虽然 swagger 很多的注解让很多代码洁癖开发者很是无奈,但是由于缺乏其他突破性的解决方案的开源,很多人只能忍痛使用。
2018 年 smart-doc 的开源终于打破的 swagger 注解侵入性的魔咒。smart-doc 完全采用源代码扫描分析来生成文档,工具通过解析代码中的接口定义、解析注释、分析项目依赖加载源码帮助用户生成接口文档。下面来看看 smart-doc 的功能特性。
smart-doc 是一款同时支持 JAVA REST API 和 Apache Dubbo RPC 接口文档生成的工具,smart-doc 在业内率先提出基于 JAVA 泛型定义推导的理念, 完全基于接口源码来分析生成接口文档,不采用任何注解侵入到业务代码中。你只需要按照 java-doc 标准编写注释,smart-doc 就能帮你生成一个简易明了的 Markdown 、HTML5 、Postman Collection2.0+、OpenAPI 3.0+的文档。
功能特性 | smart-doc | swagger |
---|---|---|
代码侵入 | 无 | 注解侵入性严重 |
集成复杂度 | 简单,只需插件 | 偏复杂、硬编码配置 |
插件支持 | 有 gradle 和 maven 插件 | 无插件 |
openapi 规范支持 | 支持 openapi 3.0 | 完全支持 openapi 的版本 |
CI 构建集成 | 可在 ci 构建阶段使用 maven 或者 gradle 命令启动插件生成文档 | 不支持 |
维护持续性 | 值得信赖,开源后用户基础多,开源两年多一直持续维护 | 全球用户多,开源维护值得信赖 |
接口 debug | 2.0.0 版本开始已经支持 debug,debug 页面简洁大方,支持文件上传下载测试 | 支持,界面丑、对接口兼容度不如 smart-doc 、不支持文档下载测试。 |
smart-doc 目前已经实现了 swagger 所支持的功能,并且针对国内用户需求附加了很多契合实际的使用的功能。 使用文档也非常完善,你不需要到处百度如何集成,你只需要看项目仓库中的 wiki 文档即可学习使用。
https://gitee.com/smart-doc-team/smart-doc
smart-doc 从 2018 年开源发展到今天,离不开国内很多用户和很多企业的支持。从当初一个仅仅支持 restful 接口 文档生成的工具,逐渐发展到支持 dubbo 、支持开发接口测试。都是靠着国内用户一个一个需求推动完善的。在这里对 smart-doc 的用户说声感谢!
这是一个专为移动设备优化的页面(即为了让你能够在 Google 搜索结果里秒开这个页面),如果你希望参与 V2EX 社区的讨论,你可以继续到 V2EX 上打开本讨论主题的完整版本。
V2EX 是创意工作者们的社区,是一个分享自己正在做的有趣事物、交流想法,可以遇见新朋友甚至新机会的地方。
V2EX is a community of developers, designers and creative people.