Getting Started

Supported JDK：1.8+

Quick Start

Step One：Add Dependency

maven:

  io.github.yedaxia
  japidocs
  1.4.4

gradle:

compile 'io.github.yedaxia:japidocs:1.4.4'

Step Two：Configuration

You can run code below at any main():

DocsConfig config = new DocsConfig();
config.setProjectPath("your springboot project path"); // root project path 
config.setProjectName("ProjectName"); // project name
config.setApiVersion("V1.0");       // api version
config.setDocsPath("your api docs path"); // api docs target path
config.setAutoGenerate(Boolean.TRUE);  // auto generate 
Docs.buildHtmlDocs(config); // execute to generate 

If there is no accident, after executing the above code, you can see the generated documents in the configured directory.

Code Style Requirements

JApiDocs is implemented by parsing Java source code. To make JApiDocs work correctly, you need to follow certain coding standards in the writing of

Controller

You can refer the

SpringDemo

1. Add Necessary Code Comments

The class comment will correspond to the first-level grouping. You can also specify the group name through

@description

@param

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


/**
 * Get User List
 * @param listForm
 */
@RequestMapping(path = "list", method = {RequestMethod.GET,  RequestMethod.POST}  )
public ApiResult<pageresult>&gt; list(UserListForm listForm){
    return null;
}

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

/**
 * Delete User
 * @param userId user id
 */
@PostMapping("delete")
public ApiResult deleteUser(@RequestParam Long userId){
    return null;
}
}

If the submitted form is

application/x-www-form-urlencoded

@param

// in @param
@param userId user id

// at FormBean
public class UserListForm extends PageForm{
    private Integer status; //user status
    private String name; //user name
}

This form type would show as table in the document：

If the submitted form is

application/json

@RequestBody

json

{
  "id": "long //user id",
  "name": "string //user name",
  "phone": "long // user phone",
  "avatar": "string // user avatar url",
  "gender": "byte //use gender"
}

2. Return Specific Class Type

We know that if a Controller Class declares @RestController, SpringBoot will return json data to the front end. JApiDocs also uses this feature to parse the result in the api method, but since JApiDocs parses the source code statically, you must clearly return a specific class type. JApiDocs supports complex class analysis such as inheritance, generics, and loop nesting.

Such as

saveUser

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

ApiResult

{
  "code": "int",
  "errMsg": "string",
  "data": {
    "userId": "string //user id",
    "userName": "string //user name",
    "friends": [
      {
        "userId": "string //user id",
        "userName": "string //user name"
      }
    ],
    "readBooks": [
      {
        "bookId": "long //book id",
        "bookName": "string //book name"
      }
    ],
    "isFollow": "boolean //is follow"
  }
}

If you don't like the return type, you can also use

@ApiDoc

@ApiDoc

3. Api Java Beans Should In Source Code

We know that there is no comment information in the compiled class bytecode. For JApiDcos to work better, your Form bean Class and return Class should be in the source code, otherwise the generated document will be missing description information. Anyway, in version 1.4.2, JApiDocs will try to parse the field information by reflection when can't find the source code (the dependent class is in the jar package).

Advanced Configuration

@ApiDoc

By default, JApiDocs only exports the api that declares

@ApiDoc

config.setAutoGenerate(Boolean.TRUE)

If you don't want to export all apis, you can turn off the

autoGenerate

@ApiDoc

Controller

Let's see how the

@ApiDoc

• result: the returned object type, it will override the returned object of SpringBoot
• url: request url，extended field, used to support non-SpringBoot projects
• method: request method，extended field, used to support non-SpringBoot projects

ex：

@ApiDoc(result = AdminVO.class, url = "/api/v1/admin/login2", method = "post")

@Ignore

Ignore Controller Class

Add

@Ignore

@Ignore
public class UserController { 

}

Ignore Method

@Ignore
@PostMapping("save")
public ApiResult saveUser(){
  return null;
}

Ignore Field

If you don’t want to export a field in the object, you can add

@Ignore

ex:

public class UserForm{
    @Ignore
    private Byte gender;
}

Export More Format

Export Markdown

config.addPlugin(new MarkdownDocPlugin());

Export Pdf Or Word

You can use pandoc convert markdown to pdf or word.

Custom Code Templates

In addition to supporting api document export, JApiDocs currently also supports the generation of return object codes for Android and iOS, corresponding to Java and Object-C languages, If you want to modify the code template, you can use the following steps:

Step One：Modify Code Templates

Copy the code templates in the

library

resources

IOS_

JAVA_

Step Two：Use The New Code Templates

Use

DocsConfig

docsConfig.setResourcePath("your new tempalte path");

More Custom Features

JApiDocs provides a plug-in interface. You can implement more rich features through the plug-in interface. The following describes how to make this:

Step One：Implements IPluginSupport Interface

public class CustomPlugin implements IPluginSupport{

@Override
public void execute(List<controllernode> controllerNodeList){
    // do something you want
}
}

Step Two：Add Your Plugin

 config.addPlugin(new CustomPlugin());