Java 零注解文档生成工具—smart-doc，看完有替换swagger的冲动

墨蓝 2023-06-15 05:59 12阅读 0赞

> Tips：喜欢的话可以关注小萌哦~~~

今天小萌给大家推荐的一个开源Java Restful API 文档生成工具，一加【oneplus】、iflytek都在用。所以，自然差不了。

# 官方简介 #

smart-doc 是一个 java restful api 文档生成工具，smart-doc 颠覆了传统类似 swagger 这种大量采用注解侵入来生成文档的实现方法。 smart-doc 完全基于接口源码分析来生成接口文档，完全做到零注解侵入，你只需要按照java标准注释的写，smart-doc 就能帮你生成一个简易明了的 Markdown、Html、AsciiDoc 文档。

如果你已经厌倦了 swagger 等文档工具的无数注解和强侵入污染，smart-doc是不错的选择！

# 最新版本 #

**smart-doc 1.7.7**

*  修改timestamp类型字段创建json示例错误bug。
 *  fix \#I1545A 单接口多路径bug。
 *  修改部分url生成部署空格问题。
 *  优化对java.util.concurrent.ConcurrentMap的解析。

# 开源地址 #

> https://gitee.com/sunyurepository/smart-doc

# 快速入门 #

**1、Getting started**

https://gitee.com/sunyurepository/api-doc-test.git

你可以启动这个Spring Boot的项目，然后访问http://localhost:8080/doc/api.html来浏览smart-doc生成的接口文档。

**2、Dependency**

<dependency>
        <groupId>com.github.shalousun</groupId>
        <artifactId>smart-doc</artifactId>
        <version>1.7.7</version>
        <scope>test</scope>
    </dependency>

**3、Create a unit test**

通过运行一个单元测试来让Smart-doc为你生成一个简洁明了的api文档。

public class ApiDocTest {
    
        /**
         * 包括设置请求头，缺失注释的字段批量在文档生成期使用定义好的注释
         */
        @Test
        public void testBuilderControllersApi() {
            ApiConfig config = new ApiConfig();
            config.setServerUrl("http://localhost:8080");
            //true会严格要求注释，推荐设置true
            config.setStrict(true);
            //true会将文档合并导出到一个markdown
            config.setAllInOne(false);
            //生成html时加密文档名不暴露controller的名称
            config.setMd5EncryptedHtmlName(true);
    
            //指定文档输出路径
            //@since 1.7 版本开始，选择生成静态html doc文档可使用该路径：DocGlobalConstants.HTML_DOC_OUT_PATH;
            config.setOutPath(DocGlobalConstants.HTML_DOC_OUT_PATH);
            // @since 1.2,如果不配置该选项，则默认匹配全部的controller,
            // 如果需要配置有多个controller可以使用逗号隔开
            config.setPackageFilters("com.power.doc.controller");
            //不指定SourcePaths默认加载代码为项目src/main/java下的,如果项目的某一些实体来自外部代码可以一起加载
            config.setSourceCodePaths(
                    //自1.7.0版本开始，在此处可以不设置本地代码路径，单独添加外部代码路径即可
    //            SourceCodePath.path().setDesc("本项目代码").setPath("src/main/java"),
                SourceCodePath.path().setDesc("加载项目外代码").setPath("E:\\ApplicationPower\\ApplicationPower\\Common-util\\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("access_token").setType("string").setDesc("Basic auth credentials"),
                    ApiReqHeader.header().setName("user_uuid").setType("string").setDesc("User Uuid key")
            );
            //对于外部jar的类，编译后注释会被擦除，无法获取注释，但是如果量比较多请使用setSourcePaths来加载外部代码
            //如果有这种场景，则自己添加字段和注释，api-doc后期遇到同名字段则直接给相应字段加注释
            config.setCustomResponseFields(
                    CustomRespField.field().setName("success").setDesc("成功返回true,失败返回false"),
                    CustomRespField.field().setName("message").setDesc("接口响应信息"),
                    CustomRespField.field().setName("data").setDesc("接口响应数据"),
                    CustomRespField.field().setName("code").setValue("00000").setDesc("响应代码")
            );
    
            //设置项目错误码列表，设置自动生成错误列表,
            List<ApiErrorCode> errorCodeList = new ArrayList<>();
            for (ErrorCodeEnum codeEnum : ErrorCodeEnum.values()) {
                ApiErrorCode errorCode = new ApiErrorCode();
                errorCode.setValue(codeEnum.getCode()).setDesc(codeEnum.getDesc());
                errorCodeList.add(errorCode);
            }
            //如果没需要可以不设置
            config.setErrorCodes(errorCodeList);
    
            //非必须只有当setAllInOne设置为true时文档变更记录才生效，https://gitee.com/sunyurepository/ApplicationPower/issues/IPS4O
            config.setRevisionLogs(
                    RevisionLog.getLog().setRevisionTime("2018/12/15").setAuthor("chen").setRemarks("测试").setStatus("创建").setVersion("V1.0"),
                    RevisionLog.getLog().setRevisionTime("2018/12/16").setAuthor("chen2").setRemarks("测试2").setStatus("修改").setVersion("V2.0")
            );
            
            //since 1.7.5
            //文档添加数据字典
            config.setDataDictionaries(
                ApiDataDictionary.dict().setTitle("订单状态").setEnumClass(OrderEnum.class).setCodeField("code").setDescField("desc"),
                ApiDataDictionary.dict().setTitle("订单状态1").setEnumClass(OrderEnum.class).setCodeField("code").setDescField("desc")
            );
    
    
            long start = System.currentTimeMillis();
            ApiDocBuilder.builderControllersApi(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);
        }
    }

**4、接口头部效果图**

![Java 零注解文档生成工具—smart-doc，看完有替换swagger的冲动][Java _smart-doc_swagger]

**5、请求参数示例效果图**

![Java 零注解文档生成工具—smart-doc，看完有替换swagger的冲动][Java _smart-doc_swagger 1]

**6、响应参数示例效果图**

![Java 零注解文档生成工具—smart-doc，看完有替换swagger的冲动][Java _smart-doc_swagger 2]

# 给使用者的建议 #

*  smart-doc虽然可以关闭注解检测，好的规范更容易让项目变得更容易维护\* smart-doc的出发的目标不是仅仅为书写接口的开发人员自己测试接口服务的，而是希望导出的文档能够用极少的变更就能做接口服务对接文档。\* smart-doc主要目的是为了减少接口文档书写和造测试模拟数据\* smart-doc拉取了大量的开源项目做了源码解析测试，开发过程中也做了很多实际场景的思考，工具开源的目的不是做着玩，而是想帮助大家解决问题。

# 评价 #

看过示例之后是不是想要有替换swagger的冲动？别着急，swagger虽然耦合很严重，但是这个也直接避免了一些懒惰的开发人员改接口不改注释的习惯。

![Java 零注解文档生成工具—smart-doc，看完有替换swagger的冲动][Java _smart-doc_swagger 3]

[Java _smart-doc_swagger]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly91cGxvYWQtaW1hZ2VzLmppYW5zaHUuaW8vdXBsb2FkX2ltYWdlcy84MTIyNzcyLWRjMzYwNzM1N2NiMTU4MTU?x-oss-process=image/format,png
[Java _smart-doc_swagger 1]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly91cGxvYWQtaW1hZ2VzLmppYW5zaHUuaW8vdXBsb2FkX2ltYWdlcy84MTIyNzcyLTJmZDVlNTg2NmRlODJmOGM?x-oss-process=image/format,png
[Java _smart-doc_swagger 2]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly91cGxvYWQtaW1hZ2VzLmppYW5zaHUuaW8vdXBsb2FkX2ltYWdlcy84MTIyNzcyLTY1MjNiYjE3ZGMyOWUwZjM?x-oss-process=image/format,png
[Java _smart-doc_swagger 3]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly91cGxvYWQtaW1hZ2VzLmppYW5zaHUuaW8vdXBsb2FkX2ltYWdlcy84MTIyNzcyLTdmMTIwODAxYThjYTU0NzA?x-oss-process=image/format,png