Spring-Boot + Api2Doc自动生成API接口文档

本文介绍一个非常好用的自动化生成 Restful API 文档的工具——Api2Doc
它基于 SpringBoot ,原理类似于 Swagger2,但比 Swagger2 要简单好用。

目录

  • 项目背景
  • Api2Doc 简介
  • 引入 Api2Doc 依赖
  • 启用 Api2Doc 服务
  • 给 Controller 类上添加文档注解
  • @Api2Doc 注解详述
  • @ApiComment 注解详述
  • @ApiError 注解详述
  • 给文档菜单项排序
  • 补充自定义文档
  • 定制文档的欢迎页
  • 定制文档的标题及图标
  • 关闭 Api2Doc 服务

项目背景

在互联网/移动互联网软件的研发过程中,大多数研发团队前后台分工是非常明确的,
后台工程师负责服务端系统的开发,一般是提供 HTTP/HTTPS 的 Restful API 接口,
前端工程师则负责 Android、iOS、H5页面的开发,需要调用 Restful API 接口。

这就需要有一套 Restful API 文档,以帮助两方在 API 接口进行沟通,并达成一致意见。
一般情况下,编写文档的工作都会落在后台工程师身上,毕竟 API 是他们提供的嘛。

但问题是,编写 Restful API 文档是一件既繁琐、又费时、还对提高技术能力没啥帮助的苦差事,
尤其在是快速迭代、需求频繁修改的项目中,改了代码还要同步改文档,
哪点改错了或改漏了都可能产生前后端实现的不一致,导致联调时发现 BUG,
这个锅最终还是要后台工程师来背(宝宝心里苦啊...)。

因此,业界就出现了一些根据代码自动生成 Restful API 文档的开源项目,
与 Spring Boot 结合比较好的是 Swagger2,Swagger2 通过读取 Controller
代码中的注解信息,来自动生成 API 文档,可以节省大量的手工编写文档的工作量。

本项目作者之前也是用的 Swagger2,但发现 Swagger2 也有好多地方用得不爽:

第一,Swagger2 的注解非常臃肿,我们看下这段代码:


@RestController
@RequestMapping(value = "/user3")
public class UserController2Swagger2 {

    @ApiOperation(value = "获取指定id用户详细信息",
            notes = "根据user的id来获取用户详细信息",
            httpMethod = "GET")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userName", value = "用户名",
                    paramType = "query", required = true, dataType = "String"),
            @ApiImplicitParam(name = "password", value = "用户密码",
                    paramType = "query", required = true, dataType = "String")
    })
    @RequestMapping(name = "用户注册", value = "/regist",
            method = RequestMethod.GET)
    public UserInfo regist(@RequestParam("userName") String userName,
                           @RequestParam("password") String password) {
        return new UserInfo();
    }
}

@ApiOperation、@ApiImplicitParam 都是 Swagger2 提供的注解,用于定义 API 信息。
其实,API 方法本身就包含了很多信息,如HTTP Method、参数名、参数类型等等,
像 @ApiImplicitParam 中除了 value 属性有用外,其它都是重复描述。

第二,Swagger2 的页面排版不太友好,它是一个垂直排列的方式,不利于信息的展示。
并且看 API 详细信息还要一个个展开,中间还夹杂着测试的功能,反正作为文档是不易于阅读;
至于作为测试工具嘛...,现在专业的测试工具也有很多,测试人员好像也不选它。

第三,Swagger2 还有好多细节没做好,比如看这个图:

Spring-Boot + Api2Doc自动生成API接口文档_第1张图片

红框中的 API 其实对应的是同一个方法,之所以有这么多,只是因为写这个方法
时没有指定 method:

@RestController
@RequestMapping(value = "/user2")
public class UserController2Swagger2 {

    @RequestMapping(value = "/do_something")
    public void doSomethingRequiredLogon() {
    }

    // 其它方法,这里省略...
}

(当没指定 method 时,Spring Boot 会默认让这个接口支持所有的 method)

因此,考虑到与其长长久久忍受 Swagger2 的各种不爽,不如花些时间做一个
更好用的“自动化文档系统”,于是就诞生了本项目: Api2Doc 。

 

Api2Doc 简介

Api2Doc 专注于 Restful API 文档的自动生成,它的原理与 Swagger2 是类似的,
都是通过反射,分析 Controller 中的信息生成文档,但它要比 Swagger2 好很多。

最大的不同是: Api2Doc 比 Swagger2 要少写很多代码

举个例子,使用 Swagger2 的代码是这样的:


@RestController
@RequestMapping(value = "/user")
public class UserController {

    @ApiOperation(value = "添加用户", httpMethod = "POST",
            notes = "向用户组中添加用户,可以指定用户的类型")
    @ApiImplicitParams({
            @ApiImplicitParam(name = 

你可能感兴趣的:(接口开发,spring,boot)