JAVA中自定义扩展Swagger的能力，自动生成参数取值含义说明

Java佳佳

关注

已于 2022-11-09 11:57:14 修改 · 1.8k 阅读

原创

本文为博客 VIP 文章，开通 VIP 后可阅读全文

开通 VIP

大家好，又见面了。

在JAVA做前后端分离的项目开发的时候，服务端需要提供接口文档供周边人员做接口的对接指导。越来越多的项目都在尝试使用一些基于代码自动生成接口文档的工具来替代由开发人员手动编写接口文档，而Swagger作为一款优秀的在线接口文档生成工具，以其功能强大、集成方便而得到了广泛的使用。

在项目中有一种非常常见的场景，就是接口的请求或者响应参数中会有一些字段的取值会限定为固定的几个可选值之一，而在代码中这些可选值往往会通过定义枚举类的方式来承载，比如：

根据操作类型，过滤对应类型的用户操作日志列表
如:
http://127.0.0.1:8088/test/queryOperateLogs?operateType=2

这里的请求参数operateType传入的值需要在后端约定的取值范围内，这个取值范围的定义如下：

@Getter
@AllArgsConstructor
public enum OperateType {
    ADD(1, "新增或者创建操作"),
    MODIFY(2, "更新已有数据操作"),
    DELETE(3, "删除数据操作"),
    QUERY(4, "查询数据操作");

    private int value;
    private String desc;
}

这里就需要我们在接口文档里面将此接口中operateType的可选值以及每个可选值对应的含义信息都说明清楚，这样调用方在使用的时候才知道应该传入什么值。

我们基于Swagger提供的基础注解能力来实现时，比较常见的会看到如下两种写法：

写法1：接口定义的时候，指定入参的取值说明

接口URL中携带的请求入参信息，通过@ApiImplicitParam注解来告诉调用方此接口允许接收的合法operateType的取值范围以及各个取值的含义。

比如下面这种场景：

@GetMapping("/queryOperateLogs")
@ApiOperation("查询指定操作类型的操作日志列表")
@ApiImplicitParam(name = "operateType", value = "操作类型，取值说明： 1，新增；2，更新；3，除；4，查询", dataType = "int", paramType = "query")
public List<OperateLog> queryOperateLogs(int operateType) {
    return testService.queryOperateLogs(operateType);
}

这样，在swagger界面上就可以显示出字段的取值说明信息。

其实还有一种写法，即在代码的入参前面添加@ApiParam注解的方式来实现。比如：

    @GetMapping("/queryOperateLogs")
    @ApiOperation("查询指定操作类型的操作日志列表")
    public List<OperateLog> queryOperateLogs(@ApiParam(value = "操作类型，取值说明： 1，新增；2，更新；3，删除；4，查询") @RequestParam("type") int operateType) {
        return testService.queryOperateLogs(operateType);
    }

这样也能达到相同的效果。