8.6 KiB

Raw Blame History

Smart-Doc Project

Introduce

Smart-doc is a java restful api document generation tool. Smart-doc is based on interface source code analysis to generate interface documents, and zero annotation intrusion. You only need to write java standard comments when developing, smart-doc can help you generate a simple and clear markdown Or a static html document. If you are tired of the numerous annotations and strong intrusion code contamination of document tools like swagger, then hug smart-doc!

Features

Zero annotation, zero learning cost, only need to write standard java document comments.
Automatic derivation based on source code interface definition, powerful return structure derivation support.
Support Spring MVC, Spring Boot, Spring Boot Web Flux (Controller mode writing).
Supports the derivation of asynchronous interface returns such as Callable, Future, CompletableFuture.
Support JAVA's JSR303 parameter verification specification.
Support for automatic generation of request examples based on request parameters.
Support for generating json return value examples.
Support for loading source code from outside the project to generate field comments (including the sources jar package).
Support for generating multiple formats of documents: Markdown, HTML5, Asciidoctor,Postman Collection json.
Support for exporting error codes and data dictionary codes to API documentation.

Getting started

Smart-doc Samples。

# git clone https://github.com/shalousun/smart-doc-demo.git

This example already provides a static html document generated in advance. You can start the Spring Boot project and then go directly to http://localhost:8080/doc/api.html to view the interface documentation generated by smart-doc. Of course you can also browse http://localhost:8080/doc/api.html, which looks a html like generated by asciidoctor-maven-plugin plugin.

Dependency

maven

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

gradle

testCompile 'com.github.shalousun:smart-doc:[latest]'

Create a unit test

Just running a unit test will allow Smart-doc to generate a very concise api document for you, which is much simpler than swagger.

public class ApiDocTest {

    @Test
    public void testBuilderControllersApi() {
        ApiConfig config = new ApiConfig();
        
        //If the strict mode is set to true, Smart-doc forces that the public method in each interface in the code has a comment.
        config.setStrict(true);
        
        //When AllInOne is set to true, the document generation of all interfaces is merged into a Markdown or AsciiDoc document,
        // and the error code list is output to the bottom of the document.
        config.setAllInOne(true);
        
        //Set the api document output path.
        config.setOutPath("d:\\md");
        
        //Generating Markdown documentation
        ApiDocBuilder.buildApiDoc(config);
    }
}

Detailed use case:

public class ApiDocTest {

    @Test
    public void testBuilderControllersApi() {
        ApiConfig config = new ApiConfig();
        config.setServerUrl("http://localhost:8080");
        
        //If the strict mode is set to true, Smart-doc forces that the public method in each interface in the code has a comment.
        config.setStrict(true);
        
        //When AllInOne is set to true, the document generation of all interfaces is merged into a Markdown or AsciiDoc document,
        // and the error code list is output to the bottom of the document.
        config.setAllInOne(true);
        
        //Set the api document output path.
        config.setOutPath("d:\\md");
        
        //since smart-doc 1.7.5
        //corverd old AllIneOne.md  file generated by smart-doc.
        config.setCoverOld(true);
        //since smart-doc 1.7.9, default is true
        config.setShowAuthor(false);
        //since smart-doc 1.7.5
        //set project name
        config.setProjectName("Your project name");
        // If you do not configure PackageFilters, it matches all controllers by default.
        // Configure multiple controller paths to be separated by commas
        config.setPackageFilters("com.power.doc.controller");
        
        //Set the request header, if there is no request header, you don't need to set it.
        config.setRequestHeaders(
                ApiReqHeader.header().setName("access_token").setType("string")
                        .setDesc("Basic auth credentials").setRequired(true).setSince("v1.1.0"),
                ApiReqHeader.header().setName("user_uuid").setType("string").setDesc("User Uuid key")
        );
        
        //Output a list of error codes in the project, using for example:
        List<ApiErrorCode> errorCodeList = new ArrayList<>();
        for (ErrorCodeEnum codeEnum : ErrorCodeEnum.values()) {
            ApiErrorCode errorCode = new ApiErrorCode();
            errorCode.setValue(codeEnum.getCode()).setDesc(codeEnum.getDesc());
            errorCodeList.add(errorCode);
        }
        //not necessary
        config.setErrorCodes(errorCodeList);
    
        //Set the document change record,
        //it is not necessary to have the document change record take effect only when setAllInOne is set to true.
        config.setRevisionLogs(
                RevisionLog.getLog().setRevisionTime("2018/12/15").setAuthor("chen").setRemarks("test").setStatus("create").setVersion("V1.0"),
                RevisionLog.getLog().setRevisionTime("2018/12/16").setAuthor("chen2").setRemarks("test2").setStatus("update").setVersion("V2.0")
        );
        
        //since 1.7.5
        //add data dictionary
        config.setDataDictionaries(
            ApiDataDictionary.dict().setTitle("Order status").setEnumClass(OrderEnum.class).setCodeField("code").setDescField("desc"),
            ApiDataDictionary.dict().setTitle("Order status1").setEnumClass(OrderEnum.class).setCodeField("code").setDescField("desc")
        );
        //Generating Markdown documentation
        ApiDocBuilder.buildApiDoc(config);
    }
}

Generated document example

Interface header rendering

Request parameter example rendering

Response parameter example renderings

Use Maven Plugin

Smart-doc provides a maven plugin to quickly integrate into the project to generate documentation. It is recommended that you use plugins instead of the unit tests above. smart-doc-maven-plugin

Building

you can build with the following commands. (Java 1.8 is required to build the master branch)

mvn clean install -Dmaven.test.skip=true

Other reference

Smart-doc manual

Who is using

These are only part of the companies using smart-doc, for reference only. If you are using smart-doc, please add your company here to tell us your scenario to make smart-doc better.

OnePlus Xiaomi yuanmengjiankang zhongkezhilian puqie