smart-doc

smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具，smart-doc在业内率先提出基于java泛型定义推导的理念， 完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。你只需要按照javadoc标准编写注释， smart-doc就能帮你生成一个简易明了的Markdown、HTML5文档，甚至可以直接生成Postman collection导入到Postman做api接口调试 smart-doc 1.9.8 已经发布，此版本更新内容包括： New Features 增加对抽象Controller方法的解析。 支持ResponseBodyAdvice通用接口响应包装设置。 忽略对Class对象的解析。 Bug Fixes 修改阿里版本dubbo注解名称解析错误。 修改模拟值生成错误。 修复类同时继承和基类和实现接口中可能出现字段重复的bug。 本文分享自微信公众号 - Laravel技术社区（Laravel360）。 如有侵权，请联系 support@oschina.cn 删除。 本文参与“ OSC源创计划 ”，欢迎正在阅读的你也加入，一起分享。 来源： oschina 链接： https://my.oschina.net/u/3372402/blog/4708798

smart-doc 是一款同时支持 java restful api 和 Apache Dubbo rpc 接口文档生成的工具，smart-doc 颠覆了传统类似 swagger 这种大量采用注解侵入来生成文档的实现方法。 smart-doc 完全基于接口源码分析来生成接口文档，完全做到零注解侵入，你只需要按照 java 标准注释编写，smart-doc 就能帮你生成一个简易明了的 markdown 或是一个像 GitBook 样式的静态 html 文档。如果你已经厌倦了 swagger 等文档工具的无数注解和强侵入污染，那请拥抱 smart-doc 吧！ 功能特性 支持接口 debug。 零注解、零学习成本、只需要写标准 java 注释。 基于源代码接口定义自动推导，强大的返回结构推导。 支持 Spring MVC,Spring Boot,Spring Boot Web Flux(controller 书写方式)。 支持 Callable,Future,CompletableFuture 等异步接口返回的推导。 支持 JavaBean 上的 JSR303 参数校验规范，支持分组验证。 对 json 请求参数的接口能够自动生成模拟 json 参数。 对一些常用字段定义能够生成有效的模拟值。 支持生成 json 返回值示例。 支持从项目外部加载源代码来生成字段注释(包括标准规范发布的

1、设置方法注释 首先每个人都应该拥有写注释的规范，IDEA设置如下： 接口统一规范 /** * * @author mujiutian * @date $DATE$ $TIME$ * @param $params$ */ 2、 pom依赖添加插件 <plugin> <groupId> com.github.shalousun </groupId> <artifactId> smart-doc-maven-plugin </artifactId> <version> 1.1.0 </version> <configuration> <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中--> <configFile> ./src/main/resources/smart-doc.json </configFile> <!--指定项目名称--> <projectName> 测试 </projectName> <!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉--> <excludes> <!--格式为：groupId:artifactId;参考如下--> <!--1.0.7版本开始你还可以用正则匹配排除,如：poi.* --> <exclude> com.alibaba:fastjson <

在国内dubbo成为很多互联网公司高并发分布式场景下rpc框架的首选，dubbo从开源至今经历过蛮多的过程，从开源到中间的停止维护，经过三年的沉寂，2017年9月，阿里巴巴宣布重启dubbo项目。到2018年2月，阿里将dubbo捐献给Apache基金会，随后dubbo经过孵化后顺利成为apache的顶级项目。 当然本文的重点不是介绍dubbo的使用，而是介绍如何利用smart-doc工具来生成dubbo的rpc内部接口文档。smart-doc因为其基于注释和java接口定义自动推导的理念，开源以来受到国内很多开发者的喜爱。在开源之初，smart-doc仅仅支持restful api文档的生成，但是在发展的过程中，不断有开发者询问smart-doc能否支持dubbo rpc接口文档的生成。经过不断努力，在smart-doc 1.8.7版本中我们增加了dubbo rpc接口的支持，下面来看看真正的操作。 一、集成smart-doc smart-doc本着使用简单的原则开发了maven插件和gradle，通过插件来降低smart-doc的集成难度和去除依赖侵入性。您可以根据自己使用的依赖构建管理工具来选择相关的插件，下面以使用smart-doc-maven-plugin插件集成smart-doc生成dubbo为例。当然集成smart-doc来生成dubbo

作为开发，写接口文档一直是一个很头痛的问题，尤其在前后端分离大量盛行的当下，后端必须要为前端同事提供明确的入参出参文档，否则整个对接工作无法顺利进行，前后端的相爱相杀的大戏时常上演。笔者刚工作的那些年，swagger都还没有正式发布，对接前端和app端的文档全靠手写markdown完成。写接口文档的时间常常感jio比写代码耗费的时间还长。随着技术的进步和众多开源人的努力，近几年针对java开发的文档生成工具越来越多。新入行的开发人员再也不用去体会过去的那些辛酸历程。在java文档生成的这个领域，swagger一直是一只领头羊。可能占据着90%的市场， 除此还有像 Spring REST Doc这些有名的工具也被大量的使用，但是这些工具在笔者看来使用比较蛮烦，侵入性高。今天笔者要给大家介绍和推荐一款本人开源的文档工具smart-doc，也会介绍如何使用这个工具来生成自己的文档。 一、当前市面上文档工具存在的问题 下面来列举当前市场上主流文档工具的问题： 侵入性强，需要编写大量注解，代表工具如：swagger，还有一些公司自研的文档工具 强依赖性，如果项目不想使用该工具，业务代码无法编译通过。 代码解析能力弱，使用文档不齐全，主要代表为国内众多开源的相关工具。 众多基于注释分析的工具无法解析jar包里面的注释(sources jar包)，需要人工配置源码路径