Extension development

Custom development extension

smart-doc uses the scanned and analyzed data as a data open interface, opening two types of API data structures, one is tiled and can be directly rendered, Another kind of API parameter relationship is replaced by a tree structure. You can choose to use different data interfaces according to your own needs.

Development case:

1. For example, after using the open interface of smart-doc to obtain data, the development tool generates a Jemeter performance test script.
2. After obtaining the data of the API interface document, the development tool generates an automated test script
3. Use development tools to import smart-doc data into some API document management systems (ps: Don’t expect too much from smart-doc officials to connect to open source document management systems on the market, because no one has become Industry technical standards so that we can be tempted to support)

Recommendation for development integration: For students who use the open data of smart-doc to develop tools, it is recommended to build a separate tool project and add smart-doc as an open source component dependency. If you make changes after fork, it will be difficult to follow the official upgrade of smart-doc, the underlying component.

Document data acquisition

Since version 1.7.0, smart-doc has opened up the API interface related information data generated after scanning the source code, that is, smart-doc is currently used to render documents in markdown, html and other formats. data, The operation of obtaining data is very simple. If your team has the ability to develop a document management system by itself, then you can completely store the interface document data obtained from smart-doc into your own document management system. smart-doc automatically makes an md5 signature for each Controller name and each interface method name, basically ensuring uniqueness. You can directly structure the document data and store it in the document management system. Doing management and presentation.

/**
     * Including setting request headers, fields with missing comments will use defined comments during document generation in batches
     */
@Test
public void testBuilderControllersApi() {
     //Config configuration information, please refer to other examples
     ApiConfig config = new ApiConfig();
    
     //The following is used after version 1.7.9. This interface is used to obtain flat parameter list data. If you want to render other documents yourself, you can use this data to render directly.
     ApiAllData apiAllData = ApiDataBuilder.getApiData(config);
     // Newly added after version 1.9.2, the data obtained by this interface converts the parameter list into a tree interface. When docking with other document management, data can be obtained from this interface for easy processing.
     ApiAllData docList = ApiDataBuilder.getApiDataTree(config);
    
}

The field information is as follows:

Field	Type	Description	Since
projectName	string	Project Name	-
projectId	string	Project ID, generated by MD5 from the name	-
language	string	Document language (can be used with custom templates)	-
apiDocList	array	API Document List	-
└─order	int32	Order of the controller, automatically sorted and generated by smart-doc	1.7+
└─name	string	Controller Class Name	-
└─alias	string	MD5 alias of the controller name	1.7+
└─list	array	List of interfaces in the controller	-
└─methodId	Method ID, generated by MD5 using controller+method	1.7.3 +
└─name	string	Method Name	1.7.3 +
└─order	int32	Interface sequence number, automatically sorted	1.7+
└─desc	string	Method Description	-
└─detail	string	Detailed introduction of the method	-
└─url	string	Controller Method URL	-
└─author	string	Interface Author Name	-
└─type	string	HTTP Request Type	-
└─headers	string	String type header concatenation, only to reduce the number of times headers are rendered in the template	-
└─contentType	string	HTTP Content Type	-
└─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	Enumeration Dictionary List	-
└─order	int32	Dictionary Order	-
└─title	string	Dictionary Name	-
└─dataDictList	array	Enumeration Dictionary Table	-
└─value	string	Dictionary Code	-
└─type	string	Dictionary Value Type	-
└─desc	string	Dictionary Description	-
└─ordinal	int32	Enumeration Order	-
└─name	string	Enumeration Order	-
errorCodeList	array	Enumeration Error List	-
└─value	string	Error Code	-
└─type	string	Error Code Type	-
└─desc	string	Error Code Description	-
└─ordinal	int32	Enumeration Error Code Order	-
└─name	string	Enumeration Name	-
revisionLogs	array	Document Change Records	-
└─version	string	Version	-
└─status	string	Status	-
└─author	string	Author	-
└─revisionTime	string	Update Time	-
└─remarks	string	Description	-

Note: The data acquisition interface has changed after 1.7.9. If you need to render the template by yourself, the final data will be the most important. ApiDataBuilder.

Other framework document parsing and development

WARNING

@since 3.0.6, you don't need to modify the source code~

smart-doc currently supports parsing at the Web and Apache Dubbo levels of the Spring technology stack. Due to limited official open source manpower, it is unable to parse other web layer frameworks. Of course, a Web level framework is required. Generally, the framework needs to meet the following conditions:

• The framework uses clear annotation routing (in layman terms, a Controller similar to Spring has a clear annotation declaring the path path), or it can be an implementation framework similar to the Jakarta RS-API 2.x specification.

Let's take a look at the implementation support writing.

Write the document construction and parsing implementation template of the framework

Here we take Quarkus, a cloud native framework that is currently popular in Java, as an example. If Quarkus is supported on smart-doc. Then first create a new QuarkusDocBuildTemplate under the com.power.doc.template package of smart-doc, and QuarkusDocBuildTemplate implements the IDocBuildTemplate interface. code show as below:

/**
 * @author yu 2021/6/28.
 */
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;
    }
}

Then I combine the use of Quarkus and refer to the current SpringBootDocBuildTemplate implementation to complete the implementation of the interface data generated by QuarkusDocBuildTemplate.

Adding SPI Configuration Files

In the src/main/resources/META-INF/services/com.ly.doc.template.IDocBuildTemplate file, add a line with the fully qualified name of the QuarkusDocBuildTemplate class:

com.demo.QuarkusDocBuildTemplate

Similarly, for the WebSocket implementation class, in the src/main/resources/META-INF/services/com.ly.doc.template.IWebSocketDocBuildTemplate file, add a line with the fully qualified name of the implementation class.

Use the newly added framework to parse

Then configure the framework name you use when using smart-doc in your project. smart-doc defaults to Spring, so the newly added framework needs to be specified in the configuration when used.

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

The development process is like this. The main difficulty lies in the implementation of IDocBuildTemplate.

Other Framework Documentation Parsing Development (Based on JAVA SPI) ^3.0.6

TIP

Starting from version 3.0.6, it is possible to add document parsing for other frameworks without modifying the source code 🎉

Currently, it supports the Spring technology stack for Web and Apache Dubbo. Due to limited resources, the official open-source team cannot cover other web layer frameworks. However, to support Web layer frameworks, they generally need to meet the following conditions:

• The framework uses explicit annotation routing (similar to how Spring's Controller has clearly declared path paths with annotations) or follows the Jakarta RS-API 2.x specification.

Here's how to implement support for other frameworks.

Plugin Integration Development

To add a parsing extension project or module for smart-doc to extend the parsing of some custom frameworks, introduce the official dependencies of smart-doc in the extension project. For the common parsing of internal enterprise frameworks, it is recommended to build the extension parsing capability using an independent project.

Core Code Implementation

Create a new module or project and include the smart-doc dependency:

<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>[latest version]</version>
        </dependency>
    </dependencies>
</project>

Implement the com.ly.doc.template.IDocBuildTemplate interface. If you want to obtain WebSocket documentation, implement the com.ly.doc.template.IWebSocketDocBuildTemplate interface and implement the relevant methods.

For example:

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.
 *
 * @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) {
        // match Quarkus
        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;
    }
}

Then add the fully qualified name of the implementation class to the resources/META-INF/services/com.ly.doc.template.IDocBuildTemplate file. If it is a WebSocket document, add the fully qualified name of the implementation class to the resources/META-INF/services/com.ly.doc.template.IWebSocketDocBuildTemplate file.

As shown below:

Installation or Deployment

Package the project into a jar file and install it into the local repository or publish it to a remote repository.

Using the Newly Added Framework Parsing

Adjust the smart-doc-maven-plugin plugin dependency configuration to add the above project dependency:

<plugin>
    <groupId>com.ly.smart-doc</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>[latest version]</version>
    <configuration>
        <!-- Specify the configuration file for generating documents -->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!-- Specify the project name -->
        <projectName>Test</projectName>
    </configuration>
    <dependencies>
        <dependency>
            <!-- Include the newly added module installed or deployed in the previous step -->
            <groupId>com.github.test</groupId>
            <artifactId>smart-doc-extend</artifactId>
            <version>1.0-SNAPSHOT</version>
        </dependency>
    </dependencies>
</plugin>

When using smart-doc in the project, configure the framework name to be used. By default, smart-doc uses Spring, so the newly added framework must be specified in the configuration file: Modify the framework configuration in the smart-doc.json file:

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

🙌Maintaining the Non-Invasive Nature of smart-doc

This approach can effectively maintain the non-invasive nature of smart-doc, and the final deployment product will not include dependencies related to smart-doc. This is also the officially recommended method.