preface

Hello everyone, my name is Ye Daxia, an independent developer. This document tool was an idea I had in 2017. At that time, I was working in the company and responsible for the development of App client. At that time, the back-end kids were not willing to write documents, and they always had to wait for them to finish the interface development before communicating the interface details on wechat. As a result, the front-end children always work overtime when the deadline is almost.

Later, I suggested that they could design the interface well first, so that we could develop in parallel, but obviously it would increase their workload, so they were not willing to do it. Against this background, I wondered if I could create a tool that would automatically generate this document without increasing their workload as much as possible.

At that time, the back end of the group was still using the Play framework. I investigated this framework, combined with the strong typing language features of Java, and had a basic idea. Therefore, I spent almost two weeks in private to make a very preliminary version, which could basically meet the requirements of documentation although simple.

This is where the original idea for JApiDocs came from.

Later, I thought that other people might also need this thing, so I put it into open source, and extended support for SpringBoot, JFinal framework.

Soon, this project was recommended by Open Source China and received a wave of stars. Later, it was invited to share it with source Innovation Club, which was the peak moment of this project.

Later, as I started my own business, I gradually had no time to take care of this project, and attention gradually decreased.

I always feel regretful that my career as a coder is not complete without a decent open source product, so I come back to continue to improve this open source tool. Although I don’t know whether it will be recognized by everyone eventually, I still want to try.

Introduction to the

Writing and maintaining API documentation is an annoying chore for back-end programmers, and we all hate it, but unless you write your own front-end and back-end code, API documentation is an essential interface for back-end collaboration.

JApiDocs is an out-of-the-box document generation tool for SpringBoot interfaces that requires no additional annotations.

No graphics, no truth, the resulting document looks like this:

Whereas Swagger writes a bunch of annotations, And Spring Rest Docs writes test cases to generate API documentation, JApiDocs features painless integration.

Quick start

For JApiDcos to work correctly, your code should look something like this:

/** * 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; }}Copy the code

We annotate the Controller class and method as necessary and return the associated object type to the interface method. Yes, JApiDocs will be able to parse the relevant interface information, just as we would normally write code, but note that you need to tell JApiDocs the parameters of the interface via @param, but with the help of the IDE, this work will be easy and pleasant:

You can then generate the document by executing the following code in either of the main entry methods:

DocsConfig config = new DocsConfig();
config.setProjectPath("your springboot project path"); // Project root directory
config.setProjectName("ProjectName"); // Project name
config.setApiVersion("V1.0");       // Declare the API version
config.setDocsPath("your api docs path"); // Generate API document directory
config.setAutoGenerate(Boolean.TRUE);  // The configuration is automatically generated
Docs.buildHtmlDocs(config); // Perform the generated document
Copy the code

Then you just write the code, and JApiDocs can do the job of generating the Api documentation. You don’t have to worry about writing and maintaining additional documentation.

features

Code is documentation

JApiDocs works by parsing SpringBoot’s source syntax directly, so as long as the Controller syntax conforms to certain code specifications and is properly commented, it can be exported directly.

2, support to export HTML

Convenient navigation and interface view interface; It can be previewed locally or deployed to an HTTP server. You are advised to deploy it on a server to facilitate collaboration between the front and back ends.

3. Export the client Model code synchronously

Support to export Java and iOS Object C Model code, reduce front-end programmer’s repetitive coding work.

4. More features

Supports interface search. Support different versions and English documents; Custom extensions, etc.

Concise documentation

No matter how useful something is, if there is no documentation, no one will get it. To get you up and running, JApiDocs comes with a minimal documentation to make sure you can use JApiDocs in just a few minutes.

Life is too short to be lazy.

Are you sure you won’t look at a productivity tool that will allow you to spend more of your time doing more valuable things in less than five minutes?

Warehouse address | Chinese documents

Tips: The best way to bookmark and support a project on GitHub is to click star!

What’s next

The goal of this tool is to maximize front-end communication and development efficiency. Upcoming plans include but are not limited to:

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

If you have a better idea, feel free to leave a comment.