实用工具：FastDoc 文档提取工具

Posted 2023-02-13 sp42a

实用工具：FastDoc 文档提取工具

简单、实用的 HTTP API 文档生成工具，支持 Spring MVC/Spring Boot 下的控制器信息提取，类似 Swagger 但稍有不同的机制。

在线演示地址在 https://framework.ajaxjs.com/demo/fast-doc/。

关于研发者这工具的动机，请参考我博客《写文档是件大事情，怎么弄好它？》。

文档的信息来自哪里？换句话说，根据哪些的信息，才能形成文档？笔者愚以为，来自下面几个方面：

• Spring MVC 各种注解，定义了这个控制器大体如何，如 @GetMapping("/test/id")，告诉了你是 GET 方法和接口地址
• Java 的注释。前面我的博文说过，基于 Java 本身的注释就够了，不是基于 Swagger 那样的自定义注解
• 前两者是主要的信息提供者。若不够或者不满足，就来像 Swagger 那样子采取自定义注解的方式。但这种方式不会太多。

有人疑问，既然有了 Swagger 注解为什么还要 Java 的注释呢？——因为没有了 Java 注释，你编码的时候就没有语法提示呀，IDE 又不会智能到可以提取注解的信息。当然，你可以复制一份到 Java 注释，但岂不是重复了么，而且手工复制？——那不符合我们程序员“懒”的追求哦。——呃～重复不是问题～～你有代码生成器？再加上，，我控制器方法不需要给其他 Java 代码提示啊～～——呃～那好吧。

Anyway，综上，笔者编写了这个小巧的工具，不仅代码行数少，精简、轻量级，而且非入侵，不会影响你原有的工程依赖，无论使用还是部署也很方便。

尽管这一个小小的工具，但不例外地，也是由前、后端两部分程序所组成。但这所谓的“后端”并不是一个 Web 程序，严格说只是一个 main() 函数或者单元测试就能运行的 Java 程序，目的是生成供给前端渲染的 JSON，这个 JSON 就包含了所有文档信息。

• 前端源码在 https://gitee.com/sp42_admin/ajaxjs/tree/master/aj-ui-widget/fast-doc。
• 生成 JSON 程序，其实是 AJAXJS Framework 的一部分，源码在 https://gitee.com/sp42_admin/ajaxjs/tree/master/aj-framework/src/main/java/com/ajaxjs/fast_doc。

使用方法

前端网页

前端网页很简单，能读取 json.js 就能解析了。你甚至可以把网页直接用浏览器 file:// 方式打开，当然更常见的是放在 nginx/Tomcat 上面。

注意 fast-doc 是里面那层目录，外面一层还有与之平级的 libs 和 common 的依赖。

另外，还有一个地方要配置，就是接口地址的前缀，更改你具体的地址。用于显示这里：

你要进入源码简单改下，编辑 doc.htm 文件约第 197 行，修改 data.root 即可。

生成 JSON

添加依赖

在你的项目工程中，添加下面两个依赖：

<dependency>
    <groupId>com.ajaxjs</groupId>
    <artifactId>ajaxjs-framework</artifactId>
    <version>1.0.7</version>
    <scope>test</scope>
</dependency>

<dependency>
    <groupId>com.ajaxjs</groupId>
    <artifactId>ajaxjs-javadoc</artifactId>
    <version>1.0.2</version>
    <scope>test</scope>
</dependency>

使用 test 的 scope 即可，这是非入侵的。然后新建一个 JUnit 单元测试（虽然 main() 函数执行也可以，但是前面已经是 test 的 Maven 依赖了，故无法 main()）。

调用方法

新建单测方法，配置参数 FastDocRun 并运行 FastDoc.run(run)：

FastDocRun run = new FastDocRun();
run.sourceDir = "D:\\\\code\\\\ajaxjs\\\\aj-framework\\\\aj-framework\\\\src\\\\test\\\\java\\\\"; // 源码目录，到 java 那一层
run.beanClasses = new Class<?>[]  FooBean.class, BarBean.class, InnerClass.class ; // 有哪些 Java Bean，都列出来
run.controllerClasses = new Class<?>[]  FooController.class ; // 有哪些 Spring MVC 控制器类，都列出来
run.jsonDir = "D:\\\\code\\\\ajaxjs\\\\aj-framework\\\\aj-ui-widget\\\\fast-doc\\\\json.js"; // 最终 JSON 保存的地方

FastDoc.run(run);

jsonDir 就是你前端要读取 json.js 文件的那个地方。运行通过之后，你要手动复制 json.js 到前端覆盖。

提示：如果 class 太多怎么办？可以通过 FastDoc.findAndAddClassesInPackageByFile() 指定某个目录返回目录下所有的类。返回的数组太多，可以通过实用工具 ListUtils.addAll(T[]... arrays) 合并为一个数组然后传到方法中。

高级用法

如果你使用 Swagger 的注解，或者自定义的注解声明文档信息，可以通过自定义提取器的方式生成 JSON。

下面假设 @Doc 是你自定义的注解，我们通过新建 DashuAnnotationParser 来提取它。

import com.ajaxjs.fast_doc.Model;
import com.ajaxjs.fast_doc.annotation.SpringMvcAnnotationParser;
import com.ajaxjs.spring.easy_controller.ControllerMethod;
import com.dashu.lazyapidoc.annotation.Doc;
import org.springframework.util.ObjectUtils;
import org.springframework.util.StringUtils;

import java.lang.annotation.Annotation;
import java.lang.reflect.Method;
import java.lang.reflect.Parameter;

public class DashuAnnotationParser extends SpringMvcAnnotationParser 
    @Override
    public void onClzInfo(Model.ControllerInfo ci, Class<?> clz) 
        Doc doc = clz.getAnnotation(Doc.class);
        if (doc != null) 
            ci.description = doc.value();
        
    

    @Override
    public void getMethodInfo(Model.Item item, Method method) 
        Doc[] annotationsByType = method.getAnnotationsByType(Doc.class);

        if (annotationsByType != null) 
            if (annotationsByType.length == 1) 
                Doc doc = annotationsByType[0];
                item.name = doc.value();

                if (StringUtils.hasText(doc.remark()))
                    item.description = doc.remark();

                return;
            

            // 多个，name 为空的那个就是
            for (Doc doc : annotationsByType) 
                if (StringUtils.isEmpty(doc.name())) 
                    item.name = doc.value();

                    if (StringUtils.hasText(doc.remark()))
                        item.description = doc.remark();

                    break;
                
            
        
    

    @Override
    public void getArgs(Model.Item item, Method method, Parameter param, Model.ArgInfo arg) 
        Doc[] annotationsByType = method.getAnnotationsByType(Doc.class);

        if (ObjectUtils.isEmpty(annotationsByType))
            return;

        for (Doc doc : annotationsByType) 
            String argName = doc.name();

            if (StringUtils.hasText(argName) && argName.equals(arg.name)) 
                arg.description = doc.value();

                if (StringUtils.hasText(doc.remark()))
                    arg.description += "。" + doc.remark();

                break;
            
        
    

DashuAnnotationParser 继承于 SpringMvcAnnotationParser，覆盖了相关的模板方法（又称虚方法），分别对应获取类信息、方法信息和金额参数信息的时候。

这样，调用 FastDoc 的方法有所不同，如下是：

Class<?>[] beans = FastDoc.findAndAddClassesInPackageByFile("org.basecode.protocol.sys.model", "C:\\\\code\\\\auth-git\\\\security-console-parent\\\\security-console-service-protocol\\\\src\\\\main\\\\java\\\\org\\\\basecode\\\\protocol\\\\sys\\\\model");
Class<?>[] dtos = FastDoc.findAndAddClassesInPackageByFile("org.basecode.protocol.sys.dto", "C:\\\\code\\\\auth-git\\\\security-console-parent\\\\security-console-service-protocol\\\\src\\\\main\\\\java\\\\org\\\\basecode\\\\protocol\\\\sys\\\\dto");
Class<?>[] vos = FastDoc.findAndAddClassesInPackageByFile("org.basecode.protocol.sys.vo", "C:\\\\code\\\\auth-git\\\\security-console-parent\\\\security-console-service-protocol\\\\src\\\\main\\\\java\\\\org\\\\basecode\\\\protocol\\\\sys\\\\vo");
Class<?>[] forms = FastDoc.findAndAddClassesInPackageByFile("org.basecode.protocol.sys.form", "C:\\\\code\\\\auth-git\\\\security-console-parent\\\\security-console-service-protocol\\\\src\\\\main\\\\java\\\\org\\\\basecode\\\\protocol\\\\sys\\\\form");

Class<?>[] all = ListUtils.concat(ListUtils.concat(beans, dtos), vos);
all = ListUtils.concat(all, forms);

FastDoc.loadBeans("C:\\\\code\\\\auth-git\\\\security-console-parent\\\\security-console-service-protocol\\\\src\\\\main\\\\java\\\\",
        all);

Class<?>[] services = FastDoc.findAndAddClassesInPackageByFile("org.basecode.protocol.sys.service", "C:\\\\code\\\\auth-git\\\\security-console-parent\\\\security-console-service-protocol\\\\src\\\\main\\\\java\\\\org\\\\basecode\\\\protocol\\\\sys\\\\service");
FastDoc.loadControllersDoc(DashuAnnotationParser.class, "C:\\\\code\\\\auth-git\\\\security-console-parent\\\\security-console-service-protocol\\\\src\\\\main\\\\java\\\\",
        services);

FastDoc.saveToDisk("C:\\\\code\\\\aj\\\\aj-all\\\\ajaxjs\\\\aj-ui-widget\\\\fast-doc\\\\json.js");

FAQ 答疑

• 如果出现如下图所示，只有成员的名称、类型等的信息，而没有注释信息，是什么原因？
  

配置有问题。能提取成员的名称、类型等的信息，已说明 classPath 配置正确，但没配置好所需的 sourcePath。你想想看，编译好的 .class 哪里有注释？肯定在 .java 文件里面才有。