请不要再使用 swagger 了，给你推荐这款工具

[smartdoc647]

在过去，尤其是 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 vs swagger

<thead> </thead>

功能特性	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

debug 页面

致谢

smart-doc 从 2018 年开源发展到今天，离不开国内很多用户和很多企业的支持。从当初一个仅仅支持 restful 接口 文档生成的工具，逐渐发展到支持 dubbo 、支持开发接口测试。都是靠着国内用户一个一个需求推动完善的。在这里对 smart-doc 的用户说声感谢！

[Lemeng]

虽然规则问题，但还是支持一下。呵呵

[cnzjl]

看着还可以

[Shawdon]

@hantsy 赞同，两种模式各有使用场景，但随着经验的积累最后会设计优先