快速开始

maven

  [xml]
1
2
3
4
5
<dependency>
  <groupId>io.github.yedaxia</groupId>
  <artifactId>japidocs</artifactId>
  <version>1.4.4</version>
</dependency>

配置

任何一个 main 方法直接运行即可：

  [java]
1
2
3
4
5
6
7
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

代码风格要求

JApiDocs 是通过解析 Java 源代码实现的。

为了让JApiDocs正常工作，项目中Controller的编写需要遵循一定的编码标准。

可以参考源码中的SpringDemo模块进行对比理解。

1. 添加必要的代码注释

班级评论将对应于第一级分组。

也可以通过@description 指定组名； JApiDocs 将使用@param 查找参数以进行进一步分析。

  [java]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
/**
 * 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<UserVO>> 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;
    }
}

如果提交的表单是 application/x-www-form-urlencoded 类型，可以在 @param 后面添加说明或者在 JavaBean 对象中添加注释：

  [java]
1
2
// in @param
@param userId user id
  [java]
1
2
3
4
5
// at FormBean
public class UserListForm extends PageForm{
    private Integer status; //user status
    private String name; //user name
}

小结

这种类似于基于 maven 插件的源码解析。

难度倒不是特别大，类似于我以前写的 maven 插件。

不过做的特性比较丰富，这一点非常难得。

参考资料

https://github.com/YeDaxia/JApiDocs