itxh/apidoc

通过JavaDoc生成OpenAPI文档

API_DOC 注释生成器

自动扫描Java上面的代码生成OpenAPI文档，无代码侵入。

对比与Swageer的代码侵入显得更加简洁。

诞生原因

在开发的过程中，尤其是联调的过程中，接口出入参的修改是很频繁的一件事。这就导致开发过程中，修改了接口参数缺忘记修改接口文档。 因此需要一个工具能够自动读取Java类中的注释来生成文档。

对比Swagger

Springfox的代码侵入性太强了，使得代码一点优雅性都没有，注解上写了说明那还要写注释么？ 而且Springfox的功能太强大，几乎能够生成所有类型的文档，但实际使用中最多的还是使用JSON作为DSL来描述。所以这个项目目前只支持了使用JSON进行出入参描述。XML啥的目前不打算支持。

基本特性

apidoc最终会把扫描路径下的所有controller解析成OpenApi 3.0协议。

controller解析:会扫描带有@Controller和@RestController的类。

URL解析:SpringMvc中定义的基本Mapping

入参解析: 如果使用@RequestBody注解则解析成JSON格式、否则就解析成param格式。

出参解析:会把所有的类都解析成JSON格式。

使用方式

看下面代码：

 @Test
public void print() throws ClassNotFoundException, IOException {
    SourceBuilder sourceBuilder = new SourceBuilder();

    Reader reader = new Reader(new OpenAPI());

    Set<JavaClass> controllerData = sourceBuilder.getControllerData();

    OpenAPI openAPI = reader.read(controllerData);
    Info info = new Info();
    // 标题
    info.title("dddd");
    // 版本
    info.setVersion("111.111");

    openAPI.setInfo(info);

    Json.pretty("/Users/openAPI.json", openAPI);
}

由于Java运行限制，目前只能运行在测试脚本或者main方法中。因为扫描注释需要编译前的类，所有不能像Springfox那样运行时生成。 有的返回的类可能被打包在其他的jar类，也注定了只能在test或者main中运行。

Yapi支持

apidoc 还提供了插件用于将扫描出来的openApi信息导入到Yapi中。

UploadToYapi uploadToYapi = new UploadToYapi("token", "http://127.0.0.1:3000");
uploadToYapi.upload(openAPI, true);

例子

展示了一个简单的controller的解析

/**
 * 测试控制器
 *
 * @author zhaotianzeng
 * @version V1.0
 * @date 2019-05-27 13:22
 */
@RequestMapping("/test")
@RestController
public class TestController {


    /**
     * 新增一个实例
     *
     * @param createParam 创建对象
     * @return 创建后的信息
     */
    @PostMapping(value = "/create")
    public CreateVO add(@RequestBody @Valid CreateParam createParam) {
        return new CreateVO();
    }

    /**
     * 新增一个实例2
     *
     * @param createParam2 创建对象2
     */
    @PostMapping(value = "/create2")
    public List<CreateVO> create2(@Valid @RequestBody List<CreateParam> createParam2) {
        return new LinkedList<>();
    }

    /**
     * 获取一个实例
     *
     * @param userId 用户ID
     * @param sex    性别
     * @return 返回信息
     */
    @GetMapping(value = "/get")
    public Result<CreateVO> get(@RequestParam(value = "userId", required = false) String userId,
                                @RequestParam(value = "sex2") String sex) {
        return new Result<>();
    }

    /**
     * 获取一个实例
     *
     * @param userId 用户ID
     * @param sex    性别
     * @return 返回信息
     */
    @GetMapping(value = "/get")
    public Result<Result2<CreateParam>> get2(@RequestParam(value = "userId", required = false) String userId,
                                             @RequestParam(value = "sex2") String sex) {
        return new Result<>();
    }


}