smart-doc 代码逆向生成接口文档

2024-01-10 17:18:46

最近领导分了一个调研smart-doc的任务，可以扫描项目中Controller类，生成接口文档，省去了人工手写文档的工作，而且随时生成，便于维护；缺点就在于，要用这个第三方工具来限制规范代码，例如方法、实体、控制层的注解编写规范，增大项目负荷。

建议刚接触的朋友根据场景，慎重考虑。

生成出来的文档支持 html markdown doc等格式，下面是HTML的

步骤1. idea加入自定义注解自动提示 @ignore,@required,@mock,@dubbo,@restApi,@order,@ignoreResponseBodyAdvice,@download,@page,@ignoreParams,@response,@date,@mapDto

smart-doc 代码逆向生成接口文档

步骤2：

这里说明一下，官方不推荐使用JUint生成方式，原因大概就是说，接口文档是很多人维护，而每人本地的代码不同，不同版本的代码生成的文档可能会内容不一致；

所以官方推荐，引用插件方式，扫描指定服务器下的jar，通过maven指令生成，本人没有测试，可参照官方文档

https://gitee.com/smart-doc-team/smart-doc/wikis/smart-doc%20maven%E6%8F%92%E4%BB%B6?sort_id=1791450

smart-doc 代码逆向生成接口文档

上图所示：

BuildApiDocTest 执行类

Constants 替换常量类

JsonBuildHelper 、 SpringBootDocBuildTemplate 可设置，覆盖源代码，实现一些定制化的标签，填补原生smart-doc的不足（例如：无法解析参数及返回值带Map类型的属性）

注意：引入路径必须遵循  package com.power.doc.helper; 和  package com.power.doc.template;

pom.xml

<dependency>
              <groupId>com.github.shalousun</groupId>
            <artifactId>smart-doc-maven-plugin</artifactId>
            <version>2.2.0</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

BuildApiDocTest

package com.foton.m2m.iov.fms.apidoc;

import java.util.Arrays;

import org.junit.Test;

import com.power.common.util.DateTimeUtil;
import com.power.doc.builder.ApiDocBuilder;
import com.power.doc.builder.HtmlApiDocBuilder;
import com.power.doc.constants.Constants;
import com.power.doc.model.ApiConfig;
import com.power.doc.model.ApiConstant;
import com.power.doc.model.RevisionLog;
import com.power.doc.model.SourceCodePath;

public class BuildApiDocTest {
    /**
     * 测试方法
     */
    @Test
    public void testBuilderControllersApiSimple() {
        ApiConfig config = new ApiConfig();
         // 严格模式
        config.setStrict(false);
        // 是否生成到一个文档中
        config.setAllInOne(true);
        config.setMd5EncryptedHtmlName(false);
        
        config.setProjectName("车队");
        // 文档输出地址
        config.setOutPath("e:\\smart-doc\\api\\fms");
        // 覆盖文件
        config.setCoverOld(true);
        // 读取项目源码地址
        config.setSourceCodePaths(
//            // smart-doc对路径自动会做处理，无论是window合适linux系统路径，直接拷贝贴入即可。可以把该生成方法添加到具体项目中生成，也可以作为一个单独项目。
            SourceCodePath.builder().setDesc("本项目代码").setPath("src/main/java"),
            SourceCodePath.builder().setDesc("FMS-API").setPath("D:\\mywork\\iov-app\\platform-iov-fms\\api\\src\\main\\java"),
            SourceCodePath.builder().setDesc("COMMON-CORE").setPath("D:\\mywork\\framework\\platform-common-core\\api\\src\\main\\java")
        );
        
        config.setIgnoreRequestParams(Arrays.asList(
            "javax.servlet.http.HttpServletRequest",
            "javax.servlet.http.HttpServletResponse"
        ));
        config.setPackageFilters("");//扫描包的过滤器 controller包过滤，多个包用英文逗号隔开
        config.setRecursionLimit(5);//设置允许递归执行的次数用于避免一些对象解析卡主，默认是7，正常为3次以内，//@since smart-doc 1.8.8版本开始
        config.setRequestExample(false);//是否将请求示例展示在文档中，默认true，@since smart-doc 1.9.0
        config.setResponseExample(true);//是否将响应示例展示在文档中，默认为true，@since  smart-doc 1.9.0
        config.setDisplayActualType(false);//配置true会在注释栏自动显示泛型的真实类型短类名，@since 1.9.6
        config.setShowAuthor(false); //是否显示接口作者名称，默认是true,不想显示可关闭
        ApiConstant apiConstant = new ApiConstant();
        apiConstant.setConstantsClass(Constants.class);
        config.setApiConstants(Arrays.asList(apiConstant));
       
        /*  设置枚举字典
        config.setDataDictionaries(
                ApiDataDictionary.builder().setTitle("订单字典").setEnumClass(OrderEnum.class).setCodeField("code").setDescField("desc")
        );
        */
        //设置请求头，如果没有请求头，可以不用设置
        /*   config.setRequestHeaders(
                   ApiReqHeader.header().setName("access_token").setType("string").setDesc("Basic auth credentials"),
                   ApiReqHeader.header().setName("user_uuid").setType("string").setDesc("User Uuid key")
           );*/
        //非必须只有当setAllInOne设置为true时文档变更记录才生效，https://gitee.com/sunyurepository/ApplicationPower/issues/IPS4O
        config.setRevisionLogs(
                RevisionLog.builder().setRevisionTime("2021/05/08").setAuthor("Itink").setRemarks("第一版").setStatus("创建").setVersion("V1.2")
                //RevisionLog.builder().setRevisionTime("2018/12/16").setAuthor("chen2").setRemarks("测试2").setStatus("修改").setVersion("V2.0")
        );
       
        long start = System.currentTimeMillis();
        // 生成adoc文件
        // AdocDocBuilder.builderControllersApi(config);
        // 生成md文件
        //ApiDocBuilder.buildApiDoc(config);
        // 生成html文件
        HtmlApiDocBuilder.buildApiDoc(config);
        long end = System.currentTimeMillis();
        DateTimeUtil.printRunTime(end, start);
    }
}

Constants

package com.foton.m2m.iov.fms.constants;

/**
 * 
 * @author hezhong 2021年7月7日
 */
public interface Constants {

    String FMS_ROOT_PATH = "/iov/fms";

    String FMS_API_ROOT_PATH = "/fmsapi";

    String FMS_ADMIN_ROOT_PATH = FMS_ROOT_PATH + "/admin";

    String SPRING_MVC_JSON_SUFFIX = ".json";

    String SPRING_MVC_HTML_SUFFIX = ".htm";
}

步骤3

smart-doc 代码逆向生成接口文档

码农公寓

相关文章