Today we give you an interface document generator – JApiDocs.

Swagger is very convenient and powerful. If there’s a downside to Swaager, it’s that annotations can be tricky to write. What if I told you there was a tool that generated documents without annotations? He is our hero today — JApiDocs.

Let’s have a look at how to use!

Add dependencies

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

2. Configure the build parameters

We create a new project, write a random main method, add the configuration to generate the document, and run the main method.

DocsConfig config = new DocsConfig();
config.setProjectPath("F: \ \ Java \ \ japi journey - the docs"); // Project root directory
config.setProjectName("japi-docs"); // Project name
config.setApiVersion("V1.0");       // Declare the API version
config.setDocsPath("F:\\test"); // Generate API document directory
config.setAutoGenerate(Boolean.TRUE);  // The configuration is automatically generated
Docs.buildHtmlDocs(config); // Perform the generated document
Copy the code

3. Coding specifications

Because JApiDocs is implemented by parsing Java source code, there are certain specifications that need to be followed if you want to implement the desired documents.

3.1 Class annotations, method annotations, and attribute annotations

If we want to generate a class comment, we can either comment the class directly, or we can do it by adding @Description.

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

/ * * *@authorJava journey *@DescriptionUser interface class *@DateThe 2020-06-15 21:46 * /
@RequestMapping("/api/user")
@RestController
public class UserController {}
Copy the code

If we want to comment a method, we can only comment it directly, not by adding @description.

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

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

JApiDocs can automatically generate entity classes. There are three ways to comment on the attributes of an entity class. The result is the same as follows:

/** * User name */
private String name;
/** * User age */
private int age;
Copy the code
// User name
private String name;
// User age
private int age;
Copy the code
private String name;// User name
private int age;// User age
Copy the code

In addition to supporting our commonly used model, it also supports IOS model generation effects as follows:

​

3.2 Request Parameters

If the submitted form is an Application/X-www-form-urlencoded key/value format, we will use @param annotation to get the parameters and add comments after the parameters, as shown in the following example:

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

Copy the code

The resulting document looks like this:

Request parameters

Parameter names type Must be describe
age int no age

If the submitted form is a JSON data format of type Application/JSON, it looks like this:

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

The resulting document looks like this:

Request parameters

{
  "name": "String // Username"."age": "Int // user age"
}
Copy the code

3.3 Response Results

We know that if the Controller declares @restController, SpringBoot will return the sequence of objects directly to the front-end in Json data format. JApiDocs also uses this feature to parse the result returned by the interface, but because JApiDocs statically parses the source code, you need to specify the type of the object returned. JApiDocs supports complex class resolution such as inheritance, generics, and loop nesting.

So we don’t need to write a comment, it will parse according to our return result, as follows:

Return result:

{
  "code": "int"."msg": "string"."data": {
    "name": "String // Username"."age": "Int // user age"}}Copy the code

In the end, we generated the interface document as follows:

Advanced configuration

4.1 @ ApiDoc

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

@apidoc has the following three properties:

  • Result: This can directly declare the returned object type, if you declare, will overwrite SpringBoot returned object
  • Url: Request URL, extended field, used to support non-Springboot projects
  • Method: Request method, extended field, used to support non-Springboot projects
@ApiDoc(result = User.class, url = "/api/user/view", method = "post")
Copy the code

4.2 @ Ignore

If you don’t want to export a field in the object, you can annotate the field with @ignore so that JApiDocs will automatically Ignore it when exporting the document.

public class User {
    @Ignore
    private int age;
}
Copy the code

Five, the summary

So much for JApiDocs, the advantages and disadvantages are easy to see. Interface documentation can be generated with almost no annotations, and the few annotations we can generate automatically through the IDE. But JApiDocs does not have Swagger online debugging. If JApiDocs supports online debugging one day, there will be a huge following. After all, no code writer likes to write unnecessary comments! ~