JApiDocs生成本地文档和PDF,MarkDown,Word等接口文档

谢烨烨

2023-12-01

第一步：添加依赖

maven:

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

第二步：配置参数

你可以在任意一个main入口运行下面的代码：

        DocsConfig config = new DocsConfig();
        config.setProjectPath("C:\\my\\study\\study"); // 项目根目录
        config.setProjectName("sevice-a"); // 项目名称
        config.setApiVersion("V1.0");       // 声明该API的版本
        config.setDocsPath("C:\\my\\study\\study\\service-a\\doc"); // 生成API 文档所在目录
        config.setAutoGenerate(Boolean.TRUE);  // 配置自动生成
        config.addPlugin(new MarkdownDocPlugin());
        Docs.buildHtmlDocs(config); // 执行生成文档

如果没有意外，执行完上面的代码后，你就可以在配置的目录中看到生成的文档了。

编码规范

ApiDocs是通过解析Java源码来实现的，要使得JApiDocs正确工作，需要你在项目中的Controller书写遵循一定的编码规范。

你可以结合源码中 SpringDemo 这个模块来对照理解。

1. 添加必要的代码注释

其中类注释会对应到一级接口分组，你也可以通过@description来指定分组名称；JApiDocs 会通过 @param 来寻找接口参数和进一步解析参数的内容。

/**
 * 用户接口
 */
@RequestMapping("/api/user/")
@RestController
public class UserController {


    /**
     * 用户列表
     * @param listForm
     */
    @RequestMapping(path = "list", method = {RequestMethod.GET,  RequestMethod.POST}  )
    public ApiResult<PageResult<UserVO>> list(UserListForm listForm){
        return null;
    }

    /**
     * 保存用户
     * @param userForm
     */
    @PostMapping(path = "save")
    public ApiResult<UserVO> saveUser(@RequestBody UserForm userForm){
        return null;
    }

    /**
     * 删除用户
     * @param userId 用户ID
     */
    @PostMapping("delete")
    public ApiResult deleteUser(@RequestParam Long userId){
        return null;
    }
}

如果提交的表单是 application/x-www-form-urlencoded 类型的key/value格式，你可以在 SpringBoot 端通过在 @param 参数后添加字段解释或者在相关的JavaBean对象里面添加解释：

// 直接在java的 @param 注解中
@param userId 用户ID

// 在FormBean对象中
public class UserListForm extends PageForm{
    private Integer status; //用户状态
    private String name; //用户名
}

这种格式对于到文档中的参数描述将是表格的形式：

参数名	类型	必须	描述
status	int	否	用户状态
name	string	否	用户名

如果提交的表单是 application/json 类型的json数据格式，对应 SpringBoot 中的 @RequestBody 注解，在文档中则是 json 格式显示：

{
  "id": "long //用户ID",
  "name": "string //用户名",
  "phone": "long //电话",
  "avatar": "string //头像",
  "gender": "byte //性别"
}

2. 接口声明返回对象

我们知道，如果Controller声明了@RestController，SpringBoot会把返回的对象直接序列成Json数据格式返回给前端。 JApiDocs也利用了这一特性来解析接口返回的结果，但由于JApiDocs是静态解析源码的，因此你要明确指出返回对象的类型信息，JApiDocs支持继承、泛型、循环嵌套等复杂的类解析。

比如上面的saveUser接口：

 /**
 * 保存用户
 * @param userForm
 */
@PostMapping(path = "save")
public ApiResult<UserVO> saveUser(@RequestBody UserForm userForm){
    return null;
}

ApiResult表明了该接口返回的数据结构，经过JApiDocs处理后是这样的：

{
  "code": "int",
  "errMsg": "string",
  "data": {
    "userId": "string //用户id",
    "userName": "string //用户名",
    "friends": [
      {
        "userId": "string //用户id",
        "userName": "string //用户名"
      }
    ],
    "readBooks": [
      {
        "bookId": "long //图书id",
        "bookName": "string //图书名称"
      }
    ],
    "isFollow": "boolean //是否关注"
  }
}

高级配置

@Ignore

忽略Controller

你只需要在Controller类上添加该注解即可，这样，整个Controller的接口都会被忽略掉：

@Ignore
public class UserController { 

}

忽略接口

不难理解，就是在接口方法中添加@Ignore注解：

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

忽略字段

如果你不想导出对象里面的某个字段，可以给这个字段加上@Ignore注解，这样JApiDocs导出文档的时候就会自动忽略掉了：

例子:

public class UserForm{
    @Ignore
    private Byte gender; //性别
}

导出更多格式

导出markdown

config.addPlugin(new MarkdownDocPlugin());

导出 pdf 或者 word

你可以通过 pandoc 把 markdown 格式转成 pdf 或者 word 格式。
也可以导出markdown 格式后通过Typora导出为word或者PDF格式
文件->导出->PDF/Word