Three solutions to quickly generate interface documents in Java

Time:2021-9-18

preface

Often, in the closing stage of a project, the customer needs the interface document of the project or a large sass platform. When each product calls each other, the other party needs to provide the interface document

Generally speaking, interface documents belong to the technical precipitation of products, which is a long-term accumulation process. However, many times, the development stage does not think so much. As a result, when interface documents are needed, they are always tired of coping. In a hurry, the most clumsy method is to copy them one by one against the project code

Here are two simple, fast and applicable solutions to help you quickly solve this problem

Scheme 1: use japidocs

This is the simplest and most efficient way to quickly generate interface documents, and it is also the least expensive way to transform existing projects

  • Can be used to generate spring boot API documents
  • Read Java doc comments without additional code modification

Basic Usage

1. Add dependency


		<dependency>
            <groupId>io.github.yedaxia</groupId>
            <artifactId>japidocs</artifactId>
            <version>1.4.3</version>
        </dependency>

2. Under a package in the project, add a class

在这里插入图片描述

For example, there is a testapi class in which a main party is added. You can use the following template code. When you use it yourself, you need to simply modify several places, including the project root directory and the directory of the generated document

public class TestApi {

    public static void main(String[] args) {
        DocsConfig config = new DocsConfig();
        //Project root directory
        Config.setprojectpath ("E: \ \ learning code \ \ assemblyone \ \ Web");
        //Project name
        config.setProjectName("Assembly");
        //Declare the version of the API
        config.setApiVersion("V2.0");
        //Directory where API documents are generated
        Config.setdocspath ("E: \ \ learning code \ \ assemblyone");
        //Configure automatic generation
        config.setAutoGenerate(Boolean.TRUE);
        //Execute generate document
        Docs.buildHtmlDocs(config);
    }

}

Here, suppose there is a usercontroller interface class in the project

@RestController
@RequestMapping(value = "/api2doc")
public class UserController {

    /**
     *Get user message
     * @return
     */
    @Apicomment ("get user.")
    @GetMapping("/getUser")
    public User getUser() {
        User user = new User();
        user.setGroup("group1");
        user.setName("first-group");
        return user;
    }

    /**
     *New user
     *@ param group user group name
     *@ param name base name
     * @return
     */
    @Apicomment ("add new user")
    @Getmapping (name = "new user", value = "new user")
    public String addUser(String group, String name) {
        return " group:" + group + " ==== " + "name :" + name;
    }

}

There is an entity class user

@Data
public class User {

    /**
     *ID primary key
     */
    private Long id;

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

    /**
     *Account password
     */
    private String password;

    /**
     *User's group
     */
    private String group;

    /**
     *User type
     */
    private UserType type;

    /**
     *Deleted
     */
    private Boolean deleted;

    /**
     *Creation time
     */
    private Date createTime;

}

In order to make the generated documents look more perfect, the comments on the names of each interface of the controller and the fields in the entity must be as complete as possible

Then run the main method and generate it

在这里插入图片描述

Then you will find that HTML documents are generated for each controller class in the project under the specified file directory. You might as well open it and have a look

在这里插入图片描述

This effect is also very conscientious. Is it worth celebrating here? Of course, there are more functions for japidocs. Interested students can continue to study it in depth

Option 2, swagger + knife4j

I believe that students who have used the springboot framework must be familiar with the swagger plug-in. The integration of swagger in springboot can help us quickly debug the interface, so as to improve the interface debugging efficiency of developers

However, if you use swagger only, the effect is often not ideal. For example, it is a little difficult to export a deliverable interface document using swagger, which requires swagger to be used together with knife4j

Generation steps

1. Import dependent


		<dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.4</version>
        </dependency>
		
		<!--swagger-ui-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>${swagger-bootstrap-ui.version}</version>
        </dependency>

2. Add swagger configuration class

@Configuration
@EnableSwagger2
@EnableKnife4j
public class ApiSwagger2 {

    @Bean
    public Docket createRestBmbsApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("users")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.congge.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                . title ("user related API")
                .version("1.0")
                .build();
    }

}

3. After starting the project, visit the following addresses respectively

http://localhost:8048/swagger-ui.html

在这里插入图片描述

You must be familiar with this interface. This is the swagger interface. You can quickly debug the interface on this interface

http://localhost:8048/doc.html#/home

在这里插入图片描述

在这里插入图片描述

This interface is the effect displayed after the integration of knife4j. Does this effect look better

在这里插入图片描述

Click to the document management menu bar, which provides several common interface document methods that can be downloaded. For example, take HTML as an example, click download, and then see the effect

在这里插入图片描述

Scheme 3, open source interface document generation tool

Two are recommended here

1. Japi is an open source project. Git can be downloaded and run locally. You need to install the node environment

Here is an article for reference:https://www.jb51.net/article/218568.htm

2. Use the API post tool to quickly generate online interface documents

Apipost is an API debugging and management tool that supports teamwork and can directly generate documents. It supports simulating common requests such as post, get and put. It is a rare tool for background interface developers or front-end and interface testers. Users can not only use apiopst to debug the interface, but also write relevant notes (interface documents) to easily generate online interface documents with good readability and beautiful interface.

To use apipost, you need to download the official installation package and then install it locally. The software download address on the official website is: https://www.apipost.cn/

Apipost is widely used by many developers, testers and project managers because of its powerful function. Many test colleagues use this tool in the product test team where Xiaobian is located

For Xiaobian, all troublesome things adopt a conservative attitude, but this tool is really worth recommending and learning. The interface style is very similar to postman. Here is a document detailing the use of apipost for reference and learning: https://www.cnblogs.com/gina61/articles/12931356.html

summary

This is the end of this article on three solutions for Java rapid generation of interface documents. For more information about Java rapid generation of interface documents, please search the previous articles of developeppaer or continue to browse the relevant articles below. I hope you will support developeppaer in the future!