smart-doc-group

扩展开发

自定义开发扩展

smart-doc将扫描后分析后的数据做了数据开放接口，开放了两种类型的API数据结构，一种是平铺可直接渲染的，另外一种API的参数关系准换成了树状结构的方式。可以根据自己需要去选择使用不同的数据接口。

开发案例：

如使用smart-doc的开放接口获取到数据后，开发工具生成一个Jemeter性能测试脚本。
获取到API接口文档的数据后，开发工具生成自动化测试脚本
开发工具将smart-doc的数据导入到一些API文档管理系统( ps:不要过多指望smart-doc官方去对接市面上的开源文档管理系统，因为没有谁成为了行业技术标准而让我们可以动心去支持 )

开发集成推荐：对于使用smart-doc的开放数据来开发工具的同学，建议自己单独建工具项目将smart-doc作为开源组件依赖进入。如果你fork后修改很难跟随官方升级smart-doc这个底层组件。

文档数据获取

自1.7.0版本开始smart-doc开放了扫描源代码后生成的API接口相关信息数据，即smart-doc当前用于渲染markdown、html等格式文档的数据，获取数据的操作很简单,如果自己团队有能力自己开发文档管理系统，那你完全从smart-doc获取到的接口文档数据存入到自己的文档管理系统中， smart-doc对每个Controller的名称和每个接口方法名称都自动做了md5签名，基本保证了唯一性，你完全可以直接将文档数据结构化后存入到文档管理系统在做管理和展示。

/**
    * 包括设置请求头，缺失注释的字段批量在文档生成期使用定义好的注释
    */
@Test
public void testBuilderControllersApi() {
    //config的配置信息请参考其他例子
    ApiConfig config = new ApiConfig();
    
    //1.7.9版本后使用如下，该接口用于获取平面式的参数列表数据，如果想自己渲染其他文档，可使用该数据来直接渲染。
    ApiAllData apiAllData = ApiDataBuilder.getApiData(config);
    // 1.9.2版本后开始新增，该接口获取的数据是将参数列表转换成了树形接口，在对接其他文档管理可以从该接口获取数据方便处理。
    ApiAllData docList = ApiDataBuilder.getApiDataTree(config);
    
}

字段信息如下：

Field	Type	Description	Since
projectName	string	项目名称	-
projectId	string	项目id,名称做md5生成	-
language	string	文档生语言(自定义模板可使用)	-
apiDocList	array	接口文档列表	-
└─order	int32	controller的顺序，smart-doc自动排序生成	1.7+
└─name	string	controller类名	-
└─alias	string	controller名称做md5后的别名	1.7+
└─list	array	controller中的接口列表	-
└─methodId	方法id，使用controller+method做md5取32位	1.7.3 +
└─name	string	method name	1.7.3 +
└─order	int32	接口序号，自动排序	1.7+
└─desc	string	method description	-
└─detail	string	detailed introduction of the method	-
└─url	string	controller method url	-
└─author	string	接口作者名称	-
└─type	string	http request type	-
└─headers	string	string类型的header拼接，只是为了在模板渲染是减少headers的渲染次数	-
└─contentType	string	http contentType	-
└─requestHeaders	array	http request headers	-
└─name	string	Request header name	-
└─type	string	Request header type	-
└─desc	string	Request header description	-
└─required	boolean	required flag	1.7.0
└─since	string	Starting version number	1.7.0
└─requestParams	array	http request params	-
└─field	string	field	-
└─type	string	field type	-
└─desc	string	description	-
└─required	boolean	require flag	-
└─version	string	version	-
└─requestUsage	string	http request usage	-
└─responseUsage	string	http response usage	-
└─responseParams	array	http response params	-
└─field	string	field	-
└─type	string	field type	-
└─desc	string	description	-
└─required	boolean	require flag	-
└─version	string	version	-
└─desc	string	method description	-
apiDocDictList	array	枚举字典列表	-
└─order	int32	字典顺序	-
└─title	string	字典名称	-
└─dataDictList	array	枚举字典表	-
└─value	string	字典码	-
└─type	string	字典值类型	-
└─desc	string	字典描述	-
└─ordinal	int32	枚举顺序	-
└─name	string	枚举顺序	-
errorCodeList	array	枚举错误列表	-
└─value	string	错误码	-
└─type	string	错误码类型	-
└─desc	string	错误码描述	-
└─ordinal	int32	枚举错误码的顺序	-
└─name	string	枚举名称	-
revisionLogs	array	文档变更记录	-
└─version	string	version	-
└─status	string	status	-
└─author	string	author	-
└─revisionTime	string	update time	-
└─remarks	string	description	-

注意： 1.7.9后获取数据接口有变更，需要自行渲染模板的，以最终数据为重。ApiDataBuilder。

其他框架文档解析开发

:::warning @since 3.0.6 之后，可以不修改源码了~ :::

smart-doc目前支持Spring技术栈Web和Apache Dubbo层面的解析。由于官方开源人力有限，因此无法去满足解析其他的web层框架。当然要Web层面的框架，一般需要框架需要满足下面的条件：

框架使用明确的注解路由(通俗就是说类似Spring的Controller有明确的注解申明path路径)，也可以是类似Jakarta RS-API 2.x规范的实现框架。

下面来看下实现支持编写。

编写框架的文档构建解析实现模板

这里拿当前Java比较火的一个云原生框架Quarkus为例。如果在smart-doc上支持Quarkus。那么首先在smart-doc的com.power.doc.template包下新建一个QuarkusDocBuildTemplate, QuarkusDocBuildTemplate实现IDocBuildTemplate接口。代码如下：

/**
 * @author yu 2021/6/28.
 */
public class QuarkusDocBuildTemplate implements IDocBuildTemplate<ApiDoc>{

    /**
     * 生成整个项目的文档数据
     * @param projectBuilder
     * @return
     */
    @Override
    public List<ApiDoc> getApiData(ProjectDocConfigBuilder projectBuilder) {
        return null;
    }

    /**
     * 生成单个接口类的文档(不要求实现，官方不支持)
     * @param projectBuilder
     * @param apiClassName
     * @return
     */
    @Override
    public ApiDoc getSingleApiData(ProjectDocConfigBuilder projectBuilder, String apiClassName) {
        return null;
    }

    @Override
    public boolean ignoreReturnObject(String typeName, List<String> ignoreParams) {
        return false;
    }
}

然后自己结合Quarkus的使用和参照目前的SpringBootDocBuildTemplate实现把QuarkusDocBuildTemplate生成接口数据的实现补充完整。

修改框架支持枚举

修改com.power.doc.constants中的FrameworkEnum, 添加Quarkus。

/**
 * Smart-doc Supported Framework
 *
 * @author yu 2021/6/27.
 */
public enum FrameworkEnum {

    /**
     * Apache Dubbo
     */
    DUBBO("dubbo", "com.power.doc.template.RpcDocBuildTemplate"),

    /**
     * Spring Framework
     */
    SPRING("spring", "com.power.doc.template.SpringBootDocBuildTemplate"),

    /**
     * Quarkus Framework
     */
    QUARKUS("quarkus","com.power.doc.template.QuarkusDocBuildTemplate");

    // 省略多行

}

使用新添加的框架解析

然后在项目中使用smart-doc时配置自己使用的框架名称。smart-doc默认是Spring, 因此新加的框架使用时需要配置中指定。

{
  "serverUrl": "http://127.0.0.1",
  "isStrict": false,
  "allInOne": true,
  "outPath": "D://md2",
  "framework": "quarkus"
}

开发流程就是这样，主要的难点在于IDocBuildTemplate的实现处理。

其他框架文档解析开发（基于`JAVA SPI`）

:::tip @since 3.0.6 开始，支持不修改源码的情况下，新增其他框架文档的解析🎉 :::

目前支持Spring技术栈Web、Apache Dubbo层面的解析。由于官方开源人力有限，因此无法去满足解析其他的web层框架。当然要Web层面的框架，一般需要框架需要满足下面的条件：

框架使用明确的注解路由(通俗就是说类似Spring的Controller有明确的注解申明path路径)，也可以是类似Jakarta RS-API 2.x规范的实现框架。

下面来看下实现支持编写。

插件引入开发

新增一个smart-doc的解析扩展项目或模块，用于扩展解析一些自定义的框架，在扩展项目中引入smart-doc官方的依赖。对于企业内部框架通用解析，推荐采用独立项目来构建扩展解析能力

核心代码编写

新增一个模块或项目，引入smart-doc依赖

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.github.test</groupId>
    <artifactId>smart-doc-extend</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>


    <dependencies>
        <dependency>
            <groupId>com.ly.smart-doc</groupId>
            <artifactId>smart-doc</artifactId>
            <version>[最新版]</version>
        </dependency>
    </dependencies>
</project>

实现com.power.doc.spi.DocBuildTemplate接口，如果要获取WebSocket文档，则实现com.ly.doc.template.IWebSocketDocBuildTemplate接口，并实现相关方法, 示例代码如下：

package com.github.test;

import com.ly.doc.builder.ProjectDocConfigBuilder;
import com.ly.doc.model.ApiDoc;
import com.ly.doc.model.ApiSchema;
import com.ly.doc.model.annotation.FrameworkAnnotations;
import com.ly.doc.template.IDocBuildTemplate;
import com.thoughtworks.qdox.model.JavaClass;

import java.util.Collection;

/**
 * QuarkusDocBuildTemplate.
 *
 * @author test
 * @version 1.0.0
 * @since 2024-07-02 13:43:50
 */
public class QuarkusDocBuildTemplate implements IDocBuildTemplate<ApiDoc> {

    /**
     * render api
     *
     * @param projectBuilder   ProjectDocConfigBuilder
     * @param candidateClasses candidate classes
     * @return api ApiSchema
     */
    @Override
    public ApiSchema<ApiDoc> renderApi(ProjectDocConfigBuilder projectBuilder, Collection<JavaClass> candidateClasses) {
        return null;
    }

    /**
     * support framework.
     *
     * @param framework framework
     * @return boolean
     */
    @Override
    public boolean supportsFramework(String framework) {
        // 匹配
        return "Quarkus".equalsIgnoreCase(framework);
    }

    /**
     * registered annotations.
     *
     * @return registered annotations
     */
    @Override
    public FrameworkAnnotations registeredAnnotations() {
        return null;
    }

    /**
     * is entry point.
     *
     * @param javaClass            javaClass
     * @param frameworkAnnotations frameworkAnnotations
     * @return is entry point
     */
    @Override
    public boolean isEntryPoint(JavaClass javaClass, FrameworkAnnotations frameworkAnnotations) {
        return false;
    }
}

然后在 resources/META-INF/services/com.ly.doc.spi.DocBuildTemplate 文件中添加实现类的全类名。如果是WebSocket文档则在resources/META-INF/services/com.ly.doc.template.IWebSocketDocBuildTemplate 文件中添加实现类的全类名。

如下图所示： project

安装或部署

将项目打包成jar包，并安装到本地仓库或发布到远程仓库。

使用新添加的框架解析

调整 smart-doc-maven-plugin 插件依赖配置，新增上述项目的依赖：

      <plugin>
        <groupId>com.ly.smart-doc</groupId>
        <artifactId>smart-doc-maven-plugin</artifactId>
        <version>[最新版]</version>
        <configuration>
          <!--指定生成文档的使用的配置文件-->
          <configFile>./src/main/resources/smart-doc.json</configFile>
          <!--指定项目名称-->
          <projectName>测试</projectName>
        </configuration>
        <dependencies>
        <dependency>
            <!--引入上一步安装或部署的新增模块-->
            <groupId>com.github.test</groupId>
            <artifactId>smart-doc-extend</artifactId>
            <version>1.0-SNAPSHOT</version>
        </dependency>
    </dependencies>
      </plugin>

在项目中使用 smart-doc 时配置所使用的框架名称。默认情况下，smart-doc 使用 Spring，因此新加的框架需在配置文件中指定： smart-doc.json 文件中修改 framework 配置：

{
  "serverUrl": "http://127.0.0.1",
  "isStrict": false,
  "allInOne": true,
  "outPath": "D://md2",
  "framework": "quarkus"
}

🙌保持 `smart-doc` 非侵入性特性的方法

这种方法可以很好地保持 smart-doc 的非侵入性特性，最终的部署产品将不会包含与 smart-doc 相关的依赖。这也是官方推荐的方式。

This site is open source. Improve this page.

smart-doc-group

扩展开发

自定义开发扩展

文档数据获取

其他框架文档解析开发

编写框架的文档构建解析实现模板

修改框架支持枚举

使用新添加的框架解析

其他框架文档解析开发（基于JAVA SPI）

插件引入开发

核心代码编写

安装或部署

使用新添加的框架解析

🙌保持 smart-doc 非侵入性特性的方法

其他框架文档解析开发（基于`JAVA SPI`）

🙌保持 `smart-doc` 非侵入性特性的方法