说明

维护过项目的人应该都有体会, 如果接口文档是单独编写的(org-mode、markdown、rap 甚至是 word 等),

随着项目周期的推进, 接口文档和真实代码之间的差距会越来越远.

基于 swagger 的一些细节不那么让人如意(比如无法处理 map, swagger-ui 中查看响应说明需要切屏, 把脑袋理解成是一台计算机, 眼睛是输入设备,

在看到返回的 json 时, 眼球会自己 parse 成对应的对象, 这时候你还无法确定各个字段的说明, 得切屏才能知道, 脑子会想办法把两者关联起来,

但是同一时间只能看到一个, 且切屏后的说明跟原来的排列并不一致, 于是只能不停的切, 这会加重将两者关联起来的心智负担)而出现了此文档收集应用.

使用

添加引用

com.github.liuanxin

api-document

0.8.1

添加配置

@Configuration

@EnableApiInfo

public class ApiInfoConfig {

// 可以在不同的 profile 中设置不同的值, 如:

// application.yml => online: false

// application-test.yml => online: false

// application-prod.yml => online: true

@Value("${online:false}")

private boolean online;

@Bean

public DocumentCopyright apiCopyright() {

return new DocumentCopyright("标题", "团队", "版本号", "版权")

// // true 则不进行文档收集, 默认是 false

// .setOnline(online)

// // 当某些接口不好标 @ApiIgnore 时(格式: url|method, url 可以使用 * 通配 method 可以忽略)

// .setIgnoreUrlSet(Sets.newHashSet("/user*", "/product/info|post"))

// // 全局的响应说明, 如果类或方法上有 @ApiResponses 则以它们为准

// .setGlobalResponse(Arrays.asList(

// new DocumentResponse(400, "参数有误"),

// new DocumentResponse(500, "请求异常").setResponse(XXX.class) // 见 @ApiReturnType 示例说明

// ))

// // 全局 token, 这个配置会生成在每个接口的参数中,

// // 如果想在具体的接口上忽略这些配置 或者 设置不同的参数 请使用 @ApiTokens 注解

// .setGlobalTokens(Arrays.asList(

// DocumentParam.buildToken("x-token", "认证数据", "abc", ParamType.Header).setHasTextarea("1"),

// DocumentParam.buildToken("x-version", "接口版本", "1.0.0", ParamType.Query).setMust("1")

// ))

// // 字段说明是否输出在返回示例中, 不设置则默认是 true,

// // 设置为 false 将会单独罗列, 方法上标了则以方法上的为准

// .setCommentInReturnExample(false)

// // 用在多文档收集, 是否将项目合并后输出, 默认是 false

// // 如果为 true, 请务必保证所有项目的全局响应说明和全局 token 是一致的,

// // 附加在一起并去重(当前做法)可能会导致文档错误;

// // -----

// // 如果是 false, 将在页面上选择项目进行请求, 请务必保证设置的项目都开启了 cors,

// // 否则将会因为跨域问题导致无法访问

// .setProjectMerge(true)

// // 收集其他项目的文档

// .setProjectMap(new LinkedHashMap() {{

// // key 格式: 名称-说明, 如: user-用户. value 是项目地址, 如: http://ip:port

// put("user-用户", "http://ip:port/user");

// put("product-商品", "http://ip:port/product");

// }})

;

}

}

而后在对应的 controller 层标注相应的注解(只对 @RestController 或 @ResponseBody 相关的类及接口进行文档收集,

如果方法上的返回类型是 List、Set 或 Map 会以 ArrayList、HashSet 及 HashMap 进行处理),

ResponseEntity 或 Callable 或 DeferredResult 或 WebAsyncTask 会处理其定义的泛型类型(不设置将无法解析)

PS: 可以参考 示例项目(spring boot 2) 的全局处理.

泛型请务必使用确切的类型, 如 等, 如果使用 这样的类型将会无法解析.

@SpringBootApplication

public class ExampleApplication {

public static void main(String[] args) {

SpringApplication.run(ExampleApplication.class, args);

}

}

@ApiGroup("example-示例")

@RestController

public class ExampleController {

@ApiMethod("用户列表")

@GetMapping("/example")

public JsonResult> example(@ApiParam("类型") String type, Page page) {

return JsonResult.success("示例接口", Arrays.asList(new DemoVo()));

}

}

@Data

public class Page {

@ApiParam("当前页数")

private Integer page;

@ApiParam("每页条数")

private Integer limit;

...

}

@Data

public class JsonResult {

@ApiReturn("返回码")

private JsonCode code;

@ApiReturn("返回说明")

private String msg;

@ApiReturn("返回数据")

@JsonInclude(JsonInclude.Include.NON_NULL)

private T data;

...

}

public enum JsonCode {

SUCCESS(200, "成功"),

NOT_LOGIN(401, "未登录"),

FAIL(500, "内部错误或业务异常");

int code;

String value;

JsonCode(int code, String value) {

this.code = code;

this.value = value;

}

...

}

@Data

public class DemoVo {

private Long id;

@ApiReturn("名称")

private String name;

...

}

注解说明

@ApiGroup --> 标注在类或方法上. 表示当前接口隶属哪个模块. 如果类上和方法上都标了则以方法上的为准

value --> 模块说明. 必须设置, 示例(名称-说明, 如: user-用户, 名称用来生成锚点,

说明用来显示, 以 英文中横线 - 隔开, 说明如果为空则显示成名称)

index --> 索引, 可以不设置, 越小越靠前. 可以不设置(索引如果一致会使用 说明 排序,

说明如果也一致会使用 名称 排序), 同一模块在不同的地方标注且索引不同时, 以小的索引为主

@ApiResponses --> 标注在类或方法上. 用来标注接口的响应码或描述

value --> @ApiResponse[], 必须设置

@ApiResponse --> 嵌套注解

code --> 响应码, 必须设置, 如 400

msg --> 响应说明, 必须设置, 如 参数不正确

type --> 嵌套注解 @ApiReturnType[] 定义返回类型, 可以不设置

示例如下:

@ApiResponses({ // 标注在类或接口上表示相关的接口会返回指定的响应, 否则会走全局的响应配置

@ApiResponse(code = 400, msg = "参数有误", type = { @ApiReturnType(XXX.class }),

@ApiResponse(code = 500, msg = "请求异常")

})

@ApiReturnType --> 嵌套注解, 用在 @ApiResponse 或 @ApiMethod 中

value --> 返回类型, 必须设置

generic --> 返回类型的泛型类型, 可以不设置

genericParent --> 返回类型中泛型类型的父层级, 可以不设置

genericChild --> 返回类型的泛型类型的子层级, 可以不设置

示例如下:

XXX ==> @ApiReturnType(XXX.class)

List ==> @ApiReturnType(value = List.class, generic = XXX.class)

Set ==> @ApiReturnType(value = Set.class, generic = XXX.class)

Map ==> @ApiReturnType(value = Map.class, generic = { String.class, XXX.class })

JsonResult ==> @ApiReturnType(value = JsonResult.class, generic = XXX.class)

JsonResult> ==> @ApiReturnType(

value = JsonResult.class,

genericParent = List.class,

generic = XXX.class

)

JsonResult> ==> @ApiReturnType(

value = JsonResult.class,

genericParent = Set.class,

generic = XXX.class

)

JsonResult> ==> @ApiReturnType(

value = JsonResult.class,

genericParent = Map.class,

generic = { String.class, XXX.class }

)

JsonResult> ==> @ApiReturnType(

value = JsonResult.class,

genericParent = YYY.class,

generic = XXX.class

)

JsonResult>> ==> @ApiReturnType(

value = JsonResult.class,

genericParent = YYY.class,

generic = List.class,

genericChild = XXX.class

)

JsonResult>> ==> @ApiReturnType(

value = JsonResult.class,

genericParent = YYY.class,

generic = Set.class,

genericChild = XXX.class

)

JsonResult>> ==> @ApiReturnType(

value = JsonResult.class,

genericParent = YYY.class,

generic = Map.class,

genericChild = { String.class, XXX.class }

)

@ApiMethod --> 标注在方法上

value --> 接口标题, 必须设置

develop --> 开发者信息, 可以不设置

desc --> 接口详细说明. 可以不设置

index --> 索引, 越小越靠前. 可以不设置(索引如果一致会使用 开发者信息 排序,

开发者信息 如果也一致会使用 接口标题 排序)

commentInReturnExample --> 返回字段说明是否写在返回示例中, 可以不设置,

如果设置为 false 所有的字段说明将会在返回示例的下面单独罗列.

不设置则以全局设置为准

returnType --> 嵌套注解 @ApiReturnType[] 自定义返回类型, 可以不设置, 如果设置将忽略方法上的返回类型

@ApiIgnore --> 标注在类或方法上. 当想要在某个类或接口上忽略收集时, 使用此注释

value --> 值如果是 false 则表示不忽略. 类上和方法上都标了则以方法上的为准

@ApiParam --> 标注在参数上(如果参数是由实体注入的, 则在实体的字段上标注)

value --> 参数说明, 可以不设置

name --> 参数名, 可以不设置, 如果设置了将会无视参数名或字段名

dataType --> 数据类型. 可以不设置, 自定义时(比如参数类型是枚举,

但是显示在文档上时可以传 int 时)有用: int、long、float、double、date、phone、email、url、ipv4

example --> 参数示例. 用在接口示例时有用, 可以不设置

paramType --> 参数类型. 可以不设置, Header 或 Query 两种, 默认是 Query

must --> 参数是否必须. 可以不设置, 如果标有 @RequestParam(required = true) etc... 则无视此设置

textarea --> 参数是否显示成文本域, 可以不设置, 默认是 false

datePattern --> 时间格式. 可以不设置, 如: yyyy-MM-dd HH:mm:ss

style --> 参数在页面上的样式, 可以不设置, 如: color:green;height:35px;

@ApiParamIgnore --> 标注在参数上(如果参数是由实体注入的, 则在实体的字段上标注). 如果不希望参数出现在文档中, 使用此注解

@ApiReturn --> 标注在字段上. 用来说明返回结果

value --> 返回说明, 可以不设置

name --> 返回名称, 可以不设置, 如果设置了将忽略字段名, 如果有用到 @JsonProperty 则使用其设置的值

type --> 返回类型, 可以不设置, 自定义(比如字段类型是枚举, 但是显示在文档上时是 int 时)用到

example --> 返回示例, 可以不设置, 只用在字段是 String 或基础数据类型(包括 BigInteger 和 BigDecimal)上

@ApiReturnIgnore --> 标注在字段上. 如果不希望返回字段出现在结果文档中, 使用此注解, 在字段上标注 @JsonIgnore 也是一样的

@ApiTokens --> 标注在类或方法上

useGlobal --> 是否使用全局 token, 可以不设置, 默认是 false

value --> @ApiToken[], 可以不设置, 表示当前接口需要传递的 token 信息

@ApiToken --> 嵌套注解

name --> 参数名. 必须设置

desc --> 参数说明. 可以不设置

example --> 参数示例. 用在接口示例时有用, 可以不设置

dataType --> 参数类型. 可以不设置. 如: int、long、float、double、date、phone、email、url、ipv4

paramType --> 参数类型. 可以不设置. Header 或 Query 两种, 默认是 Header

must --> 参数是否必须. 可以不设置, 默认是 false

textarea --> 参数是否显示成文本域, 用在接口示例时有用, 可以不设置, 默认是 false

datePattern --> 参数类型是 date 时的时间格式. 可以不设置, 如: yyyy-MM-dd HH:mm:ss

style --> 参数在页面上 的样式, 可以不设置

示例如下:

@ApiTokens // 标注在类或接口上表示相关的接口将不会生成全局的 token 信息

@ApiTokens({ // 标注在类或接口上表示相关的接口将会使用参数中指定的 token 信息

@ApiToken(name = "x-token", desc = "认证数据", example = "abc-xyz", textarea = true),

@ApiToken(name = "x-version", desc = "接口版本", example = "1.0", paramType = ParamType.Query, must = true)

})

@ApiModel --> 结合了 @ApiParam 和 @ApiReturn 两个注解的注解,

可以同时说明请求参数和返回字段, 请不要滥用, 应该尽量用前两者

value --> 返回或参数说明, 可以不设置

name --> 返回或参数名, 可以不设置, 如果设置了将会无视参数名或字段名

dataType --> 返回或参数的数据类型. 可以不设置, 自定义时有用: int、long、float、double、date、phone、email、url、ipv4

example --> 返回或参数的示例. 用在接口示例时有用, 可以不设置

-- 上面的属性同时作用在 请求参数 和 返回字段 上, 下面的属性只用在 请求参数 上

paramType --> 参数类型. 可以不设置, Header 或 Query 两种, 默认是 Query

must --> 参数是否必须. 可以不设置, 如果标有 @RequestParam(required = true) etc... 则无视此设置

textarea --> 参数是否显示成文本域, 可以不设置, 默认是 false

datePattern --> 时间格式. 可以不设置, 如: YYYY-MM-DD HH:mm:ss

style --> 参数在页面上的样式, 可以不设置, 如: color:green;height:35px;

如果是非 spring boot 项目, 添加如下配置

运行项目, 访问页面 http://ip:port/static/api-info.html (spring boot 则不需要 /static 二级目录)

页面 http://ip:port/static/api-info-example.html 直接请求后台接口

字段说明不显示在返回示例中, 单独罗列