I open sourced a small tool that can help you easily generate SpringBoot API documentation

Posted Jun 15, 20205 min read

Foreword

Hello everyone, my name is Ye Daxia, an independent developer. This documentation tool was an idea for me for 17 years. At that time, I was still working in the company, responsible for the development of the App client. At that time, the willingness of the back-end children's shoes to write documents was relatively low. They always had to wait for them to develop the interface before they were on WeChat. Communication interface details, obviously this kind of efficiency is very low, resulting in front-end children's shoes always work almost deadline when overtime.

Later I suggest that they can design the interface first, so that everyone can develop in parallel, but it will obviously increase their workload, so they are not happy. In this context, I wonder if I can build a tool to automatically generate this document, and try not to increase their workload.

At that time, the back-end in the group was still using the play framework. I investigated this framework, combined with the strong language features of java, and had a basic idea. So I spent almost two weeks privately to make a very preliminary version, although Simple, but basically can meet the needs of the document.

This is the original source of ideas for JApiDocs.

Later, I think this thing may be needed by others, and I will sort it out and open source later, and extend the support of Spring Boot and JFinal framework.

Soon, this project was recommended by Open Source China, and a wave of stars was harvested. Later, he was invited to share with the source creation meeting. This is the peak moment of this project.

Later, because I came out to start a business, I slowly didn't have time to take care of this project, and my attention gradually slowed down.

There is always a regret in my heart. If I don t have a decent open source product in my career, I feel that it is not very satisfactory. So I come back to continue to improve this open source tool. Although I don t know if it will eventually be approved by everyone, I still want to try it.

Introduction

Writing and maintaining API documentation is an annoying thing for back-end programmers, but we have to do it. We do not like to write documentation, but unless the front-end and back-end code of the project is written by ourselves, otherwise the API documentation It will be an indispensable communication interface in front-end and back-end collaboration.

JApiDocs is a tool for generating the SpringBoot interface document out of the box without additional annotations. **

No picture and no truth, the effect of generating documents is as follows:

Compared to Swagger, which has to write a bunch of comments, Spring Rest Docs needs to write test cases to generate API documents. JApiDocs has the characteristics of painless integration.

Quick start

For JApiDcos to work correctly, the code you write should look like the following:

/**
 * User interface
 */
@RequestMapping("/api/user/")
@RestController
public class UserController {
    /**
     * user list
     * @param listForm
     */
    @RequestMapping(path = "list", method = {RequestMethod.GET, RequestMethod.POST})
    public ApiResult<PageResult<UserVO>> list(UserListForm listForm){
        return null;
    }

    /**
     * Save user
     * @param userForm
     */
    @PostMapping(path = "save")
    public ApiResult<UserVO> saveUser(@RequestBody UserForm userForm){
        return null;
    }
}

We add the necessary annotations to the Controller class and method, and return the relevant object type to the interface method. Yes, so JApiDocs can parse the relevant interface information, which is almost the same as the code we usually write, but pay attention, You need to tell JApiDocs the parameters of the interface through @param, but with the help of the IDE, this work will be easy and pleasant:

Then you can generate the document by executing the following code in any main entry method:

DocsConfig config = new DocsConfig();
config.setProjectPath("your springboot project path"); //project root directory
config.setProjectName("ProjectName"); //project name
config.setApiVersion("V1.0"); //Declare the version of the API
config.setDocsPath("your api docs path"); //The directory where the API documentation is generated
config.setAutoGenerate(Boolean.TRUE); //Configure automatic generation
Docs.buildHtmlDocs(config); //Execute to generate documentation

Next, you just write the code, and the work of generating Api documents can be handed over to JApiDocs , you don t need to write and maintain additional documents And troubled.

Features

  1. The code is the document

JApiDocs works by directly parsing SpringBoot s source code syntax, so as long as the Controller s syntax meets certain code specifications and there are reasonable comments, You can directly export the document.

  1. Support export HTML

Convenient navigation and interface viewing interface; can be previewed locally or deployed to an HTTP server. It is recommended to deploy to the server to facilitate front-end and back-end collaboration.

  1. Simultaneously export client model code

Support for exporting Java and iOS Object C Model code on the Android side to reduce the repetitive coding work of front-end programmers.

  1. More features

Support interface search; support different versions and English documents; custom extensions, etc.

Concise documentation

No matter how easy to use, if there is no documentation, no one else can start. In order to get everyone started as soon as possible, JApiDocs has prepared a minimalist document description to ensure that you can use [JApiDocs]in a few minutes https://japidocs.agilestudio.cn/#/zh-cn/ ).

Life is short, you must be lazy.

It takes less than 5 minutes to recognize a tool that improves work efficiency, allowing you to spend more time on more valuable things. Are you sure you don t want to take a look?

Warehouse address | Chinese document

_Reminder:The best way to collect and support a project on GitHub is to order a star! _

The next plan

The goal of this tool is very clear, which is to improve the efficiency of front-end and back-end communication and development as much as possible. The following plans include but are not limited to:

  1. Support more export document formats;
  2. Automatically generate front-end interface codes for direct use by App or web page front-end development students;
  3. Identify the changed interface;
  4. Connect to some open source mock platforms, etc.

Open source is not easy, everyone is welcome to pay attention and support!