文章目录

smart-doc介绍
smart-doc特性
smart-doc的最佳搭档
谁在使用smart-doc
smart-doc的优缺点
smart-doc和swagger区别比较
smart-doc的使用姿势
- 姿势一
- 姿势二
- 姿势三（公司内部推荐使用）
总结

smart-doc介绍

一个 java restful api 文档生成工具，不用像Swagger一样写大量注解，完全基于接口源码分析来生成接口文档，但是需要按照 java的标准注释写。

完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。

你只需要按照java-doc标准编写注释， smart-doc就能帮你生成一个简易明了的Markdown、HTML5、Postman ollection2.0+、OpenAPI 3.0+的文档。

注意：需要完全按照java的标准注释，如果方法注释包含特殊符号或者换行的话，生成的json是会出现格式错误，但是不影响相关的html使用。

smart-doc特性

零注解、零学习成本、只需要写标准JAVA注释。
基于源代码接口定义自动推导，强大的返回结构推导。
支持Spring MVC、Spring Boot、Spring Boot Web Flux(Controller书写方式)Feign。
支持Callable、Future、CompletableFuture等异步接口返回的推导。
支持JavaBean上的JSR303参数校验规范，包括分组验证。
对JSON请求参数的接口能够自动生成模拟JSON参数。
对一些常用字段定义能够生成有效的模拟值。
支持生成JSON返回值示例。
支持从项目外部加载源代码来生成字段注释(包括标准规范发布的jar包)。
支持生成多种格式文档：Markdown、HTML5、Asciidoctor、Postman Collection、OpenAPI 3.0。开放文档数据，可自由实现接入文档管理系统。
支持导出错误码和定义在代码中的各种字典码到接口文档。
支持Maven、Gradle插件式轻松集成。
支持Apache Dubbo RPC接口文档生成。
debug接口调试html5页面完全支持文件上传，下载(@download tag标记下载方法)测试。

smart-doc的最佳搭档

smart-doc + Torna 组成的文档生成和管理解决方案，使用smart-doc无侵入完成JAVA源代码分析和提取注释生成API文档，自动将文档推送到Torna企业级接口文档管理平台。

谁在使用smart-doc

smart-doc的优缺点

简单总结了几个特别明显以及我认为最关键的几个优点如下：

非侵入式接口文档生成
需要按照java文档注释规范对接口及相关对象添加注释
编译文件后需要手动运行插件生成接口文档
配置简单，只需要引入插件，配置文档输出位置即可。相关更加复杂的配置根据需要自行配置。
无需启动项目，生成文档后可直接浏览

缺点
我总结了一下我使用过程中的缺点，在此我仅代表我自己提出的缺点如下

生成的openapi.json数据时，不支持泛型的多层嵌套解析，导致不同接口的responseBody解析为一个。比如接口返回为：ResultVO<DefinePage<AiOptimizationCampaignReportVO>>，解析成ResultVODefinePage（新版本已解决）

smart-doc和swagger区别比较

功能特性	smart-doc	swagger
代码侵入	无	注解侵入性严重
集成复杂度	简单，只需插件	偏复杂
插件支持	有 gradle 和 maven 插件	无插件
openapi 规范支持	支持 openapi 3.0	完全支持 openapi 的版本
CI 构建集成	可在 ci 构建阶段使用maven 或者 gradle 命令启动插件生成文档	不支持
集中化文档中心集成	已经和 torna 企业级接口文档管理平台对接	不支持
维护持续性	值得信赖，开源后用户基础多，一直持续维护	全球用户多，开源维护值得信赖
接口 debug	2.0.0 版本开始已经支持 debug，页面比 swagger 漂亮太多了。	支持

Smart-doc 从 2.0.0 后几乎实现了 swagger ui 的功能，并且比 swagger ui 更简洁大方，也更符合国内开发者的诉求。当然 smart-doc 的功能也已经超过了 swagger 为 java 开发者提供的功能。当然 smart-doc 本身是只支持扫描代码生成 openapi 3.0 的文档的，也可以将生成的 openapi 3.0 文档导入到其他 ui 中渲染展示。

swagger 生成离线的文档需要借助第三方jar包实现，而 smart-doc 直接运行 test 方法就可以直接导出 md，html，asciidoc 等格式文档。

设计思路不同，smart-doc 是基于源码分析的，它生成api文档是通过分析JAVA源码主要是通过注释和系统自带注解，来实现文档的生成，而 swagger 是运行时自动生成在线文档，并且生成测试接口的案例。由于他们设计思路理念不一样，swagger2 使用过程需要使用它定义的@API 相关注解，这样就污染了源码，代码入侵有点高，而smart -doc 就不一样了，主要是通过注释、解析/** */ 来生成API文档的。这样基本上没有入侵性，很自由！

swagger

侵入式接口文档生成
每个接口及每个实体类都需要添加注解
配置复杂，需要添加依赖然后需要添加相关配置
编译后自动生成接口文档
需要启动后才能查看，如果配置了安全框架还需要开放相关接口

smart-doc的使用姿势

姿势一

使用maven或者gradle插件进行一键生成对应的文档格式或者命令进行生成，在这里我只展示了maven插件的使用姿势。

<plugin><groupId>com.github.shalousun</groupId><artifactId>smart-doc-maven-plugin</artifactId><version>2.4.9</version><configuration><!--指定生成文档的使用的配置文件,配置文件放在自己的项目中--><configFile>./src/main/resources/smart-doc.json</configFile><!--指定项目名称--><projectName>测试</projectName><!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉--><excludes><!--格式为：groupId:artifactId;参考如下--><!--也可以支持正则式如：com.alibaba:.* --><exclude>com.alibaba:fastjson</exclude></excludes><!--includes配置用于配置加载外部依赖源码,配置后插件会按照配置项加载外部源代码而不是自动加载所有，因此使用时需要注意--><!--smart-doc能自动分析依赖树加载所有依赖源码，原则上会影响文档构建效率，因此你可以使用includes来让插件加载你配置的组件--><includes><!--格式为：groupId:artifactId;参考如下--><!--也可以支持正则式如：com.alibaba:.* --><include>com.alibaba:fastjson</include><!-- 如果配置了includes的情况下， 使用了mybatis-plus的分页需要include所使用的源码包 --><include>com.baomidou:mybatis-plus-extension</include><!-- 如果配置了includes的情况下， 使用了jpa的分页需要include所使用的源码包 --><include>org.springframework.data:spring-data-commons</include></includes></configuration><executions><execution><!--如果不需要在执行编译时启动smart-doc，则将phase注释掉--><phase>compile</phase><goals><!--smart-doc提供了html、openapi、markdown等goal，可按需配置--><goal>html</goal></goals></execution></executions>
</plugin>

使用maven插件命令如下：

//生成html
mvn -Dfile.encoding=UTF-8 smart-doc:html
//生成markdown
mvn -Dfile.encoding=UTF-8 smart-doc:markdown
//生成adoc
mvn -Dfile.encoding=UTF-8 smart-doc:adoc
//生成postman json数据
mvn -Dfile.encoding=UTF-8 smart-doc:postman
// 生成 Open Api 3.0+,Since smart-doc-maven-plugin 1.1.5
mvn -Dfile.encoding=UTF-8 smart-doc:openapi
// 生成文档推送到Torna平台
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest// Apache Dubbo RPC文档
// Generate html
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-html
// Generate markdown
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-markdown
// Generate adoc
mvn -Dfile.encoding=UTF-8 smart-doc:rpc-adoc// 生成dubbo接口文档推送到torna
mvn -Dfile.encoding=UTF-8 smart-doc:torna-rpc

使用IDE一键生成如下：

优点：便捷，快速上手

缺点：每个服务各自指定smart-doc的配置文件smart-doc.json

姿势二

导入相关smart-doc依赖

<!--导入Smart-doc依赖-->
<dependency><groupId>com.github.shalousun</groupId><artifactId>smart-doc</artifactId><version>2.5.1</version>
</dependency>

手动为每个项目引入以上jar包，可以使用smart-doc.json配置文件也可以使用smart-doc自带的ApiConfig配置类进行手动配置。

使用单元测试测试API文档生成如下：

@Test
public void testBuilderControllersApi() {ApiConfig config = new ApiConfig();config.setServerUrl("http://localhost:8080");//当把AllInOne设置为true时，Smart-doc将会把所有接口生成到一个Markdown、HHTML或者AsciiDoc中config.setAllInOne(true);//HTML5文档，建议直接放到src/main/resources/static/doc下，Smart-doc提供一个配置常量HTML_DOC_OUT_PATH//源码---String HTML_DOC_OUT_PATH = "src/main/resources/static/doc";config.setOutPath("src/main/resources/static/doc");// 设置接口包扫描路径过滤，如果不配置则Smart-doc默认扫描所有的接口类// 配置多个报名有英文逗号隔开config.setPackageFilters("com.***.Controller.*");//设置错误错列表，遍历自己的错误码设置给Smart-doc即可List<ApiErrorCode> errorCodeList = new ArrayList<>();for (HttpCodeEnum codeEnum : HttpCodeEnum.values()) {ApiErrorCode errorCode = new ApiErrorCode();errorCode.setValue(codeEnum.getCode()).setDesc(codeEnum.getMessage());errorCodeList.add(errorCode);}//不需要显示错误码,则可以不用设置错误码。config.setErrorCodes(errorCodeList);//生成Markdown文件HtmlApiDocBuilder.buildApiDoc(config);
}

姿势三（公司内部推荐使用）

Q：为什么说公司内部建议使用呢？
答：每个公司都会有自己的maven仓库(几乎)，可以搞一些定制化的工具包，比如：日志、认证、链路、授权等。可以在工具包中加入smart-doc包进行简单开发。

可以这么做：
将smart-doc集成到工具包中，在工具包进行打包，提供给使用方，然后定制开发进行配置化管理

每个Java业务服务引入公共jar包，然后进行配置，自定义配置如下：

# 是否开启html生成，默认为false
smart-doc.html-enable=true
# html生成路径，默认为当前服务子目录doc下
smart-doc.out-path=/doc/
# 接口返回对象配置
smart-doc.response-class-name=com.sparkxmedia.xplatform.sd.api.common.result.ResultVO
# 自定义请求头
smart-doc.request-header.username=zane
smart-doc.request-header.user_id=1
smart-doc.request-header.authorization=test
# controller层包
smart-doc.package-filters=com.sparkxmedia.xplatform.sd.api.ai.controller.*,com.sparkxmedia.xplatform.sd.api.controller.*
# 如果使用swagger-ui替代smart-doc的html，则需配置获取openapi.json路径
springdoc.swagger-ui.url=/sd-api/doc/openapi.json

其核心代码如下：

package com.cuizb.tools.starter.config.doc;import lombok.SneakyThrows;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.ResourceUtils;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;/*** @author: Java技术债务* @Date: 2021/6/6 20:03* Describe: 跨域解决,映射生成的静态资源*/
@Slf4j
@Configuration
@EnableConfigurationProperties({ApiDocProperties.class})
public class WebMvcConfig implements WebMvcConfigurer {@Autowiredprivate ApiDocProperties apiDocProperties;/*** 解决跨域问题* @param registry*/@Overridepublic void addCorsMappings(CorsRegistry registry) {registry.addMapping("/**").allowedHeaders("*").allowedMethods("*").allowedOriginPatterns("/**").maxAge(3600);}@SneakyThrows@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {// 当前项目根路径String rootPath = ResourceUtils.getURL("").getPath();// 文档保存绝对路径rootPath = rootPath.substring(0, rootPath.length() - 1) + apiDocProperties.getOutPath();// 映射到当前项目根路径+用户自定义路径(当前仅支持当前项目下路径)String resourcesPath;if ("dev".equals(apiDocProperties.getProfileActive()) || "local".equals(apiDocProperties.getProfileActive())) {resourcesPath = "file:///" + rootPath;} else {resourcesPath = "file:///" + apiDocProperties.getOutPath();}log.info(">>>>>>>>>>>>>" + resourcesPath);//配置静态资源映射registry.addResourceHandler("/doc/static/**").addResourceLocations(resourcesPath);}}

package com.cuizb.tools.starter.config.doc;import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;import java.util.HashMap;
import java.util.Map;/*** @author Java技术债务* @date 2022-08-17 15:08* Be in awe of every code modification*/
@Data
@AllArgsConstructor
@NoArgsConstructor
@Configuration
@ConfigurationProperties(prefix = "smart-doc")
public class ApiDocProperties {@Value("${server.port}")private int port;@Value("${app.id}")private String appId;@Value("${server.servlet.context-path:}")private String pathFilter;@Value("${spring.profiles.active:dev}")private String profileActive;private boolean htmlEnable;private String outPath;private String responseClassName;private Map<String, String> requestHeader = new HashMap<>();private String packageFilters;
}

/*** @author Java技术债务* @date 2022-08-16 18:17* Be in awe of every code modification*/
@Slf4j
@EnableConfigurationProperties({ApiDocProperties.class})
@Controller
//@RequestMapping("${spring.application.name}/doc")
@Profile({"dev", "local", "qa", "test", "sit", "uat"})
@RequestMapping("/doc")
public class DocController {@Autowiredprivate ApiDocProperties apiDocProperties;private ApiDocConfig apiDocConfig;public DocController() {}@GetMapping("/openapi.json")@ResponseBodypublic String openapi() {initApiDocConfig();ApiConfig config = apiDocConfig.getApiConfig();return OpenApiBuilder.buildOpenApi(config).trim().replace(" ", "");}@GetMapping("/build")public String buildHtml() {initApiDocConfig();... ...}
}

代码解释：

WebMvcConfig解决跨域以及文件映射，由开发人员决定是否使用smart-doc生成的API接口文档页面，因为有的已经使用了其他产品，可以将smart-doc生成的json同步到现有的产品，当然如果你只使用smart-doc的话，不需要配置文件映射。
ApiDocProperties自定义配置，开发人员只关心自己当前服务的smart-doc相关配置即可
DocController工具包中的uri进行资源访问，可以自定义html，openapi.json等路径。也可以自定义开发，生成json文件或者json字符串等。

当前为了适用本公司，简单的自定义了一些开发，以下是简单的配置了一些路径资源：

获取openapi.json地址：http://localhost:port[/server-servlet-context-path]/doc/openapi.json
构建html文件地址：http://localhost:port[/server-servlet-context-path]/doc/build
html接口文档地址：http://localhost:port[/server-servlet-context-path]/doc/static/index.html

如果你想使用这种的话，你可以继续研究与开发。。。

总结

可以入手使用，关键是零侵入，还支持dubbo方式（虽然我未体验使用此方式）

谢谢阅读，如果有不一样的见解，请评论说出你的观点以及见解。。。觉得不错的话，介意点个赞吗？我知道你不介意，谢谢哈。。。

一些工具特性介绍等引用smart-doc官方文档：https://smart-doc-group.github.io/#/zh-cn/start/quickstart

猿创征文｜小而巧的API文档生成工具之smart-doc相关推荐

apiDoc 一款很不错api文档生成工具
apiDoc 一款很不错api文档生成工具,在开发接口的时候,需要给同事看相应的接口文档.给大家推荐一个生成文档的工具--apiDoc,最后生成的文档以网页的形式发布,方便快捷,便于阅读. 创建项目目 ...
springboot的api_【粉丝投稿】无需额外注解的 SpringBoot API文档生成工具
点击上方"蓝字"关注我们吧! JApiDocs是一个无需额外注解.开箱即用的SpringBoot接口文档生成工具. 编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又 ...
android api文档_【粉丝投稿】无需额外注解的 SpringBoot API文档生成工具
点击上方"蓝字"关注我们吧! JApiDocs是一个无需额外注解.开箱即用的SpringBoot接口文档生成工具. 编写和维护API文档这个事情,对于后端程序员来说,是一件恼人但又 ...
php自写api文档生成工具
框架改版后的第二个版本定下来了,这两天也比较轻松,于是就折腾给项目建个好看的api文档. 各种折腾.先是折腾phpDocumentor2,用phpdoc开源工具来建立文档,好不容易安装成功,各个模板都 ...
java smart算法_Java Restful API 文档生成工具 smart-doc
谁说生成api文档就必须要定义注解? 谁说生成接口请求和返回示例必须要在线? 用代码去探路,不断尝试更多文档交付的可能性. 如果代码有生命,为什么不换种方式和它对话! 一.背景没有背景.就自己做自己 ...
关于深度学习框架Hamaa与Python API文档生成工具Sophon
五月两场 | NVIDIA DLI 深度学习入门课程 5月19日/5月26日一天密集式学习快速带你入门阅读全文> 正文共1988个字,预计阅读时间12分钟. 前言最近三个月我主要花时间在造 ...
一款零注解侵入的 API 文档生成工具，你用过吗？
以下文章来源方志朋的博客,回复"666"获面试宝典介绍 smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具,smart ...
Api文档生成工具与Api文档的传播（pdf）
点击查看apidoc生成文档demo 1 环境和工具 win10 apidoc:注释生成api文档 wkhtmltopdf:apidoc生成的是html,不适合传播,于是通过wkhtmltopdf将h ...
[aspnetcore.apidoc]一款很不错的api文档生成工具
简单徐速一下为什么选用了aspnetcore.apidoc 而没有选用swagger 最初我们也有在试用swagger,但总是有些感觉,感觉有点不满意,就但从api文档角度来说,从前后端文档沟通角度来 ...

猿创征文｜小而巧的API文档生成工具之smart-doc