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>1.8.1</version>
    <scope>test</scope>
</dependency>

gradle

testCompile 'com.github.shalousun:smart-doc:1.8.1'

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.

     

License

Smart-doc is under the Apache 2.0 license. See the LICENSE file for details.

Contact

Email： 836575280@qq.com