Options beyond swagger

Time:2021-6-24

Today, I will give you an interface document generator — japidocs.

Swagger must have been used by everyone. It’s very convenient and powerful. If you want to say that swaager has any shortcomings, it must be that it is troublesome to write annotations. If I say there is a tool that can generate documents without annotations, are you excited? He’s our hero today, japidocs.

Now let’s see how to use it!

1、 Add dependency

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

2、 Configure build parameters

We create a new project, then write a main method casually, increase the configuration of generating documents, and then run the main method.

DocsConfig config = new DocsConfig();
Config. Setprojectpath ("F: \ \ Java journey \ \ japi Doc")// Project root
config.setProjectName("japi-docs"); //  entry name
config.setApiVersion("V1.0");       //  Declare the version of the API
config.setDocsPath("F:\\test"); //  Directory where API documents are generated
config.setAutoGenerate(Boolean.TRUE);  //  Configuration auto generation
Docs.buildHtmlDocs(config); //  Execute build document

3、 Coding specification

Because japidocs is implemented by parsing java source code, if you want to implement the desired documents, you still need to follow certain specifications.

3.1 class annotation, method annotation and property annotation

If we want to generate class comments, we can add comments directly to the class, or we can generate them by adding @ description.

/**
 *User interface class
 */
@RequestMapping("/api/user")
@RestController
public class UserController {}

/**
 *@ author Java journey
 *@ description user interface class
 * @Date 2020-06-15 21:46
 */
@RequestMapping("/api/user")
@RestController
public class UserController {}

If we want to generate comments for methods, we can only add comments directly, not by adding @ description.

/**
 *Query users
 *@ paramage age
 * @return R<User>
*/
@GetMapping("/list")
public R<User> list(@RequestParam int age){

    User = new user ("Java journey", 18);
    return R.ok(user);
}

Japidocs can automatically generate entity classes. There are three ways to annotate the attributes of entity classes. The generated effects are the same, as follows:

/**
 *User name
 */
private String name;
/**
 *User age
 */
private int age;
//User name
private String name;
//User age
private int age;
private String name;//  User name
private int age;//  User age

In addition to supporting our commonly used models, it also supports IOS model generation. The results are as follows:

Options beyond swagger

Options beyond swagger

3.2 request parameters

If the submitted form isapplication/x-www-form-urlencodedTypekey/valueFormat, we get the parameter through @ param annotation, and add a comment after the parameter. The example is as follows:

/**
  *@ paramage age
  */
@GetMapping("/list")
public R<User> list(@RequestParam int age){
    User = new user ("Java journey", 18);
    return R.ok(user);
}

The effect of the generated document is as follows:

Request parameters

Parameter name type must describe
age int no Age

If the submitted form isapplication/jsonTypejsonThe data format is as follows:

/**
  * @param user
  * @return
  */
@PostMapping("/add")
public R<User> add(@RequestBody User user){
    return R.ok(user);
}

The effect of the generated document is as follows:

Request parameters

{
  "Name": "string // user name,",
  "Age": "int // user age"
}

3.3 response results

We know that ifControllerStatement@RestControllerSpring boot will directly sequence the returned objects into JSON data format and return them to the front end. Japidocs also uses this feature to parse the results returned by the interface. However, because japidocs statically parses the source code, you should clearly indicate the type information of the returned object. Japidocs supports inheritance, generics, loop nesting and other complex class parsing.

Therefore, we don’t need to write comments any more. It will parse according to our returned results. The effect is as follows:

Return result:

{
  "code": "int",
  "msg": "string",
  "data": {
    "Name": "string // user name,",
    "Age": "int // user age"
  }
}

Finally, we generate the interface document as follows:

Options beyond swagger

4、 Advanced configuration

4.1 @ApiDoc

If you don’t want to export all interfaces, we can set config. Setautogenerate (Boolean. False) in the configuration; Then add @ apidoc to the interface you want to generate.

@Apidoc has the following three attributes:

  • Result: this can directly declare the returned object type. If you declare it, it will override the returned object of springboot
  • URL: request URL, extension field, used to support non spring boot projects
  • Method: request method, extended field, used to support non springboot projects
@ApiDoc(result = User.class, url = "/api/user/view", method = "post")

4.2 @Ignore

If you don’t want to export a field in an object, you can add@IgnoreAnnotation, so that when japidocs exports the document, it will automatically ignore it.

public class User {
    @Ignore
    private int age;
}

5、 Summary

Here is the introduction of japidocs. You can easily see the advantages and disadvantages. Almost no comments are needed to generate interface documents, and only a few comments can be generated automatically through ide. However, japidocs does not have the function of swagger online debugging. If one day japidocs supports online debugging, there will certainly be a big wave of followers. After all, who writes code likes to write redundant annotations~

Recommended Today

Collection splitting method sharing

Reprinted from: http://www.java265.com/JavaJingYan/202205/16533595033477.html   The following author describes the method of splitting a list collection into multiple small collections, as shown below Implementation ideas: Use the subList method from the list collection to split the collection into multiple sub-collections package com.java265.other; import java.util.ArrayList; import java.util.List; /* * Example sharing of list split * */ public […]