Smart-doc is a java restful api document generation tool. smart-doc overthrows the traditional method like swagger, which uses annotation intrusion to generate documents. Smrt-doc generates interface documents based on the analysis of interface source code. It is completely zero-annotation intrusion. You only need to write annotations according to java standard. Smrt-doc can help you generate a simple and clear markdown or a static html document like GitBook.
Here's how to integrate smart-doc into a Spring Book project to generate a concise api document.

Note: smart-doc has been included in open source China, and has been used by many domestic developers to generate interface documents quickly.

Smrt-doc function

• Zero annotation, zero learning cost, just need to write standard java annotations.
• Automatic deduction based on the definition of source code interface and powerful deduction of return structure.
• Support Spring MVC,Spring Boot,Spring Boot Web Flux(controller Writing).
• Support the deduction of asynchronous interface returns such as Callable, Future, Completable Future.
• Support JSR303 parameter verification specification on JavaBean.
• The interface for json request parameters can automatically generate simulated json parameters.
• Some common field definitions can generate valid simulation values.
• Support for generating json return value examples.
• Supports loading source code from outside the project to generate field annotations (including jar packages published by standard specifications).
• Support for generating multiple formats of documents: Markdown, HTML5, Asciidoctor.
• It is easy to view static HTML5 api documents online on Spring Boot service.
• Open document data can freely access document management system.

Integrating Smart-doc in Spring Book Project

Add smart-doc dependencies, and note that smart-doc does not need to be packaged into the final product package, so I recommend using only test level.

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

Create a new object:

public class User {

    /**
     * User name
     */
    private String userName;

    /**
     * Nickname?
     */
    private String nickName;

    /**
     * User address
     */
    private String userAddress;

    /**
     * User age
     */
    private int userAge;

    /**
     * Cell-phone number
     */
    private String phone;

    /**
     * Creation time
     */
    private Long createTime;

    /**
     * ipv6
     */
    private String ipv6;

    /**
     * Fixed telephone
     */
    private String telephone;
    //Omit get set
}

Next, create a new User Controller, and then test how smart-doc can easily generate documents using User as the request parameter and response entity of Controller.

@RestController
@RequestMapping("/user")
public class UserController {

    /**
     * Add user
     * @param user
     * @return
     */
    @PostMapping("/add")
    public User addUser(@RequestBody User user){
        return null;
    }
}

After adding the controller, we create a new unit test class in the project for running documents.

public class ApiDocTest {

    /**
     * Including setting request headers, batch of fields with missing annotations using well-defined annotations during document generation
     */
    @Test
    public void testBuilderControllersApi() {
        ApiConfig config = new ApiConfig();
        config.setServerUrl("http://localhost:8080");
        //True will strictly require comments and recommend setting true
        config.setStrict(true);
        //true will merge documents and export them to a markdown
        //config.setAllInOne(true);
        //Encrypted document name does not expose controller name when generating html
        config.setMd5EncryptedHtmlName(true);

        //Specify the document output path
        //@ Since version 1.7, this path can be used to generate static html doc documents: DocGlobalConstants.HTML_DOC_OUT_PATH;
        config.setOutPath("d:\\md");
        // @ since 1.2, if this option is not configured, all controller s are matched by default.
        // If you need to configure multiple controller s, you can use commas to separate them
        config.setPackageFilters("com.power.doc.controller");


        long start = System.currentTimeMillis();
        //Processing by oneself after acquiring interface data
        ApiDocBuilder.builderControllersApi(config);
        long end = System.currentTimeMillis();
        DateTimeUtil.printRunTime(end, start);
    }
}

Finally, run the smart-doc unit test to generate the markdown interface document to the specified directory. The results are as follows:

User Information Operating Interface

Add user

URL: http://localhost:8080/user/add

Type: POST

Content-Type: application/json; charset=utf-8

Request-parameters:

Request-example:

{
    "userName":"soaring flight.Congratulate",
    "nickName":"raymond.gutkowski",
    "userAddress":"Apt. 819 Xiao Bang No. 7699, Dian, Dian 852063",
    "userAge":41,
    "phone":"15018373016",
    "createTime":1569934393095,
    "ipv6":"9eb3:fada:ffd2:912e:6225:1062:a2d7:718f",
    "telephone":"15018373016"
}

Response-fields:

Response-example:

{
    "userName":"soaring flight.Congratulate",
    "nickName":"raymond.gutkowski",
    "userAddress":"Apt. 819 Xiao Bang No. 7699, Dian, Dian 852063",
    "userAge":41,
    "phone":"15018373016",
    "createTime":1569934393095,
    "ipv6":"9eb3:fada:ffd2:912e:6225:1062:a2d7:718f",
    "telephone":"15018373016"
}

Is it much simpler than swagger, and it doesn't intrude code at all, just write standard java doc comments. For more information, please check out the smart-doc project and remember to star t. View the smart-doc project

Note: This article is from the original author of smart-doc. You can reproduce it, but do not copy it as an original.