原创作者：王健
未经允许，不得用于商业用途。
笔者做为多年程序员，使用过各种不同的文档从最高的work到在线文档，到swagger（近两年以来）到目前的smart-doc。
为什么要从swagger转向使用smart-doc。因为swagger的严重侵入性，让代码多了一些维护的成本。且swagger与项目一同发布，并伴随项目一同启动（当然可以配置不启动swagger，但需要在配置添加禁用配置）。
smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具，smart-doc在业内率先提出基于JAVA泛型定义推导的理念， 完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。你只需要按照java-doc标准编写注释， smart-doc就能帮你生成一个简易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+的文档。(以下都来于官网介绍)
特点：
零注解、零学习成本、只需要写标准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。Up- 开放文档数据，可自由实现接入文档管理系统。
支持导出错误码和定义在代码中的各种字典码到接口文档。
支持Maven、Gradle插件式轻松集成。
支持Apache Dubbo RPC接口文档生成。
debug接口调试html5页面完全支持文件上传，下载(@download tag标记下载方法)测试。
参考地址：https://gitee.com/smart-doc-team/smart-doc
不多说了，直接上代码，smart-doc可以通过编码的方式生成文档，也可以通过插件的方式生成，我分别试了两种方式，发现插件生成的文档操作不太方便，所以我个人建议可以使用编码的方式实现。
步 1、在项目中添加依赖，并设置为test即可，项目发布后，不会有smart-doc的依赖
<dependency>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc</artifactId>
<version>2.2.6</version>
<scope>test</scope>
</dependency>
步2：编码代码
可以将生成的html文件，直接放到nginx目录下，这样就可以在外部直接访问了：
package com.jzjyt.oempc.smartdoc;
import com.power.doc.builder.ApiDataBuilder;
import com.power.doc.builder.ApiDocBuilder;
import com.power.doc.builder.HtmlApiDocBuilder;
import com.power.doc.builder.PostmanJsonBuilder;
import com.power.doc.builder.rpc.RpcMarkdownBuilder;
import com.power.doc.model.*;
import org.junit.jupiter.api.Test;
import java.time.LocalDate;
import java.util.ArrayList;
import java.util.List;
/**
* 生成smart-doc的文档
*/
public class SmartDoc {
@Test
public void generatorDoc() {
ApiConfig config = new ApiConfig();
config.setServerUrl("http://192.168.2.33:9934");
config.setAllInOne(true);
config.setStrict(true);
//config.setOutPath("./target/html");
config.setOutPath("D:\\program\\nginx-1.21.3\\html\\docs");
config.setProjectCName("Oempc2项目");
config.setCoverOld(true);
config.setPackageFilters("com.jzjyt.oempc.modules,com.jzjyt.common.vo");
//设置请求头
ApiReqParam header = new ApiReqParam();
header.setName("Authorization");
header.setRequired(false);
header.setDesc("认证");
header.setType("header");
header.setValue("Bearer ");
config.setRequestHeaders(header);
// 生成测试页面debug-all.html页面，并在上面可以直接测试
config.setCreateDebugPage(true);
//errorcode
ApiErrorCode e1 = new ApiErrorCode();
e1.setValue("22309");
e1.setDesc("错误状态码");
List<ApiErrorCode> list = new ArrayList<>();
list.add(e1);
config.setErrorCodes(list);
//显示Java类
config.setShowJavaType(true);
config.setShowAuthor(true);
config.setProjectCName("ProjectCNsame");
//设置作者
config.setRevisionLogs(
RevisionLog.builder().setRevisionTime(LocalDate.now().toString()).setAuthor("王健").setStatus("发布").setVersion("1.0").setRemarks("测试")
);
//外部项目添加后，必须也要添加自己的项目地址
config.setSourceCodePaths(SourceCodePath.builder().setDesc("common").setPath("E:\\gits\\jzjyt\\codeapi\\oempc2.forms\\src\\main\\java"),
SourceCodePath.builder().setDesc("project").setPath(".\\src\\main\\java"),
SourceCodePath.builder().setDesc("common").setPath("E:\\gits\\jzjyt\\oempc2\\jzjyt-base\\jzjyt-common\\src\\main\\java"));
//生成Html文档后，可以在页面上实现调用
HtmlApiDocBuilder.buildApiDoc(config);
//生成Postmain.json文件，后直接导入到postman中即可以直接使用
//PostmanJsonBuilder.buildPostmanCollection(config);
生成MarkDown文件
//ApiDocBuilder.buildApiDoc(config);
}
}
步3：生成的html文档，并可以直接在页面上调用测试
步4：生成postman的json文件，并直接导入postman中就可以直接使用了，这个功能，非常不错：
生成其他文档，不再赘述。
