小知识，大挑战！本文正在参与“程序员必备小知识”创作活动。
前言
后端开发的朋友都知道写api doc有多痛苦，不能不写，但是接口数量多尤其的项目初期，几百个接口的话，真的会累死，所以必须要用一些自动构建doc的框架
swragger 本来是第一选择，但是无奈侵入性太强，于是就有了本文的主角smart-doc，虽然也是只能构建简易版本，但是一般的项目文档够用了
官网地址
基础使用
使用起来大致两种方式
- maven插件集成，在构建项目时直接能生成最新的文档
- 用程序提前生成
目前我使用的是第二种，因为第一种支持maven多项目的时候会有点问题，一直没有成功（官网是有解决方案的），而且第二种的话，也能生成postman接口，调试也很爽
具体步骤官网有写，我只是贴一下我的配置
生成单体html形式的
/**
* 包括设置请求头，缺失注释的字段批量在文档生成期使用定义好的注释
*/
@Test
public void testBuilderControllersApi() {
ApiConfig config = new ApiConfig();
// config.setServerUrl("http://localhost:9002");
//true会严格要求注释，推荐设置true
config.setStrict(false);
//true会将文档合并导出到一个markdown
config.setAllInOne(true);
//生成html时加密文档名不暴露controller的名称
config.setMd5EncryptedHtmlName(true);
//指定文档输出路径
//@since 1.7 版本开始，选择生成静态html doc文档可使用该路径：DocGlobalConstants.HTML_DOC_OUT_PATH;
config.setOutPath("src/main/resources/static/doc_3");
// @since 1.2,如果不配置该选项，则默认匹配全部的controller,
// 如果需要配置有多个controller可以使用逗号隔开
config.setPackageFilters("com.eco.newpc.controller");
//不指定SourcePaths默认加载代码为项目src/main/java下的,如果项目的某一些实体来自外部代码可以一起加载
config.setSourceCodePaths(
//自1.7.0版本开始，在此处可以不设置本地代码路径，单独添加外部代码路径即可
// SourceCodePath.path().setDesc("本项目代码").setPath("src/main/java"),
new SourceCodePath().setDesc("加载项目外代码").setPath("/Users/hans/work_space/java_project/eco-pc-fanli/pc-common/src/main/java"),
new SourceCodePath().setDesc("加载项目外代码").setPath("src/main/java")
);
//since 1.7.5
//如果该选项的值为false,则smart-doc生成allInOne.md文件的名称会自动添加版本号
config.setCoverOld(true);
//since 1.7.5
//设置项目名(非必须)，如果不设置会导致在使用一些自动添加标题序号的工具显示的序号不正常
config.setProjectName("系统");
//设置请求头，如果没有请求头，可以不用设置
config.setRequestHeaders(
ApiReqHeader.header().setName(HttpHeaders.AUTHORIZATION).setType("string").setDesc("Basic auth credentials")
);
//对于外部jar的类，编译后注释会被擦除，无法获取注释，但是如果量比较多请使用setSourcePaths来加载外部代码
//如果有这种场景，则自己添加字段和注释，api-doc后期遇到同名字段则直接给相应字段加注释
config.setResponseBodyAdvice(BodyAdvice.builder().setClassName(ServerResponse.class.getName()).setDataField("data"));
config.setDataDictionaries(
ApiDataDictionary.builder().setEnumClass(LogTypeEnum.class).setTitle("日志类型").setCodeField("code").setDescField("desc"),
ApiDataDictionary.builder().setEnumClass(OpTypeEnum.class).setTitle("操作类型").setCodeField("code").setDescField("desc"),
ApiDataDictionary.builder().setEnumClass(OrderBindTypeEnum.class).setTitle("订单绑定类型").setCodeField("code").setDescField("desc"),
ApiDataDictionary.builder().setEnumClass(OrderStatusEnum.class).setTitle("订单类型").setCodeField("code").setDescField("desc")
);
long start = System.currentTimeMillis();
HtmlApiDocBuilder.buildApiDoc(config);
//@since 1.7+版本开始，smart-doc支持生成带书签的html文档，html文档可选择下面额方式
//HtmlApiDocBuilder.builderControllersApi(config);
//@since 1.7+版本开始，smart-doc支撑生成AsciiDoc文档，你可以把AsciiDoc转成HTML5的格式。
//@see https://gitee.com/sunyurepository/api-doc-test
//AdocDocBuilder.builderControllersApi(config);
long end = System.currentTimeMillis();
DateTimeUtil.printRunTime(end, start);
}
这种的话直接可以在浏览器中访问，因为是在项目中static文件夹下
生成postman
@Test
public void toPostMan() {
ApiConfig config = new ApiConfig();
config.setServerUrl("http://{{simple-9002}}/ant");
//true会严格要求注释，推荐设置true
config.setStrict(false);
//true会将文档合并导出到一个markdown
config.setAllInOne(true);
//生成html时加密文档名不暴露controller的名称
config.setMd5EncryptedHtmlName(true);
//指定文档输出路径
//@since 1.7 版本开始，选择生成静态html doc文档可使用该路径：DocGlobalConstants.HTML_DOC_OUT_PATH;
config.setOutPath("src/main/resources/static/postman");
// @since 1.2,如果不配置该选项，则默认匹配全部的controller,
// 如果需要配置有多个controller可以使用逗号隔开
config.setPackageFilters("com.eco.newpc.controller");
//不指定SourcePaths默认加载代码为项目src/main/java下的,如果项目的某一些实体来自外部代码可以一起加载
config.setSourceCodePaths(
//自1.7.0版本开始，在此处可以不设置本地代码路径，单独添加外部代码路径即可
// SourceCodePath.path().setDesc("本项目代码").setPath("src/main/java"),
new SourceCodePath().setDesc("加载项目外代码").setPath("/Users/hans/work_space/java_project/eco-pc-fanli/pc-common/src/main/java"),
new SourceCodePath().setDesc("加载项目外代码").setPath("src/main/java")
);
//since 1.7.5
//如果该选项的值为false,则smart-doc生成allInOne.md文件的名称会自动添加版本号
config.setCoverOld(true);
//since 1.7.5
//设置项目名(非必须)，如果不设置会导致在使用一些自动添加标题序号的工具显示的序号不正常
config.setProjectName("系统");
//设置请求头，如果没有请求头，可以不用设置
config.setRequestHeaders(
ApiReqHeader.header().setName(HttpHeaders.AUTHORIZATION).setType("string").setDesc("Basic auth credentials").setValue("{{PC-Token}}").setRequired(true)
);
//对于外部jar的类，编译后注释会被擦除，无法获取注释，但是如果量比较多请使用setSourcePaths来加载外部代码
//如果有这种场景，则自己添加字段和注释，api-doc后期遇到同名字段则直接给相应字段加注释
config.setResponseBodyAdvice(BodyAdvice.builder().setClassName(ServerResponse.class.getName()).setDataField("data"));
long start = System.currentTimeMillis();
PostmanJsonBuilder.buildPostmanCollection(config);
config.setDataDictionaries(
ApiDataDictionary.builder().setEnumClass(LogTypeEnum.class).setTitle("日志类型").setCodeField("code").setDescField("desc"),
ApiDataDictionary.builder().setEnumClass(OpTypeEnum.class).setTitle("操作类型").setCodeField("code").setDescField("desc"),
ApiDataDictionary.builder().setEnumClass(OrderBindTypeEnum.class).setTitle("订单绑定类型").setCodeField("code").setDescField("desc"),
ApiDataDictionary.builder().setEnumClass(OrderStatusEnum.class).setTitle("订单类型").setCodeField("code").setDescField("desc")
);
//@since 1.7+版本开始，smart-doc支持生成带书签的html文档，html文档可选择下面额方式
//HtmlApiDocBuilder.builderControllersApi(config);
//@since 1.7+版本开始，smart-doc支撑生成AsciiDoc文档，你可以把AsciiDoc转成HTML5的格式。
//@see https://gitee.com/sunyurepository/api-doc-test
//AdocDocBuilder.builderControllersApi(config);
long end = System.currentTimeMillis();
DateTimeUtil.printRunTime(end, start);
}
不足
虽然舒服但是呢企业级别的文档还是有欠缺，可能需要自己改源码
比如说我有一个类属性是 type，int 类型，有三种，1-新 2-旧 3-未知，类似这种，这样就得在属性上加注解，比较麻烦，最好能直接识别
