A magical api documentation generator without annotation for springboot.
Supported JDK:1.8+
maven:
io.github.yedaxia japidocs 1.4.4
gradle:
compile 'io.github.yedaxia:japidocs:1.4.4'
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.
JApiDocs is implemented by parsing Java source code. To make JApiDocs work correctly, you need to follow certain coding standards in the writing of
Controllerin the project.
You can refer the
SpringDemomodule in the source code for comparison and understanding.
The class comment will correspond to the first-level grouping. You can also specify the group name through
@description; JApiDocs will use
@paramto find parameters for further analyze.
/** * 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>> 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-urlencodedtype, you can add a description after
@paramor add an comment in JavaBean object :
// 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:
parameter name |
parameter type | must | description |
---|---|---|---|
status | int | N | user status |
name | string | N | user name |
If the submitted form is
application/jsontype, corresponding to the
@RequestBodyannotation in SpringBoot, it will display as
jsonformat in the document:
{ "id": "long //user id", "name": "string //user name", "phone": "long // user phone", "avatar": "string // user avatar url", "gender": "byte //use gender" }
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; }
ApiResultshows the data structure of response,after processing by JApiDocs,it's like this:
{ "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
@ApiDocin JApiDoc to declare the response type,you can refer the
@ApiDocchapter below.
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).
By default, JApiDocs only exports the api that declares
@ApiDoc. We previously removed this restriction by setting
config.setAutoGenerate(Boolean.TRUE).
If you don't want to export all apis, you can turn off the
autoGenerateand add
@ApiDocto the
Controllerclass or api method to determine which api need to be exported.
Let's see how the
@ApiDocworks on api method:
ex:
@ApiDoc(result = AdminVO.class, url = "/api/v1/admin/login2", method = "post")
Add
@Ignoreat Controller, all of its method would ignore.
@Ignore public class UserController {}
@Ignore @PostMapping("save") public ApiResult saveUser(){ return null; }
If you don’t want to export a field in the object, you can add
@Ignoreannotation to this field, so that JApiDocs will automatically ignore it when exporting the document:
ex:
public class UserForm{ @Ignore private Byte gender; }
config.addPlugin(new MarkdownDocPlugin());
You can use pandoc convert markdown to pdf or word.
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:
Copy the code templates in the
libraryproject
resourcesdirectory of the source code, where
IOS_means Object-C code template, and
JAVA_starts with Java code, The symbol similar to "${CLASS_NAME}" in the template is a substitution variable. You will understand the meaning compare to the generated code, and try to modify it according to the code template you want.
Use
DocsConfigto replace with new template:
docsConfig.setResourcePath("your new tempalte path");
JApiDocs provides a plug-in interface. You can implement more rich features through the plug-in interface. The following describes how to make this:
public class CustomPlugin implements IPluginSupport{@Override public void execute(List<controllernode> controllerNodeList){ // do something you want }
}
config.addPlugin(new CustomPlugin());