修改接口参数名和在Swagger中的展示名-Toy模板网

这篇具有很好参考价值的文章主要介绍了修改接口参数名和在Swagger中的展示名。希望对大家有所帮助。如果存在错误或未考虑完全的地方，请大家不吝赐教，您也可以点击"举报违法"按钮提交疑问。

背景

我们有一个接口要支持后端排序，所以需要在请求对象里面增加两个参数：排序字段名、排序方式（asc、desc）。

正好基础jar包中有一个类可以直接拿来用。

@Data
public class OrderByItem {
	private String column;
    private String direction;
}

但是考虑到前端使用的是element框架，默认使用prop来定义排序字段，使用order来定义排序方式。

因此，考虑使用这两个属性来接受排序字段。但是仍然用OrderByItem这个类来接收参数。

为啥不重新定义一个类呢？

因为OrderByItem这个类还有配套的工具类，用来进行相关的转换。所以为了复用这个工具类，就有了这个奇葩需求——我要用OrderByItem这个类型来接受参数，但是这两个参数在Swagger中要展示成另外的名字，前端也需要用另外的名字来传参。

老实说，直接用column和direction没啥大问题。因此我们不去讨论这样做是否合理，姑且看如果我想实现类似的效果应该怎么处理。

JSON格式

如果OrderByItem作为JSON格式使用，那么就很简单了：

@Data
public class OrderByItem {
    @JsonProperty("prop")
	private String column;

    @JsonProperty("order")
    private String direction;
}

这里直接使用JsonProperty注解即可。

非JSON格式

如果不是JSON格式，事情会变得麻烦一点。

首先是要解决参数接收的问题，这里可以定义一个HandlerMethodArgumentResolver。

public static class OrderItemHandlerMethodArgumentResolver implements HandlerMethodArgumentResolver {

        private static final String ORDER = "order";
        private static final String ORDER_DESC = "descending";
        private static final String ORDER_ASC = "ascending";
        private static final String PROP = "prop";

        @Override
        public boolean supportsParameter(MethodParameter parameter) {
            return OrderByItem.class.isAssignableFrom(parameter.getParameterType());
        }

        @Override
        public Object resolveArgument(MethodParameter parameter, ModelAndViewContainer mavContainer, NativeWebRequest webRequest, WebDataBinderFactory binderFactory) throws Exception {

            String prop = webRequest.getParameter(PROP);
            if (StringUtils.isBlank(prop)) {
                return null;
            }

            String order = webRequest.getParameter(ORDER);
            // validate order

          	OrderByItem orderByItem = new OrderByItem();
			orderByItem.setColumn(prop);
		    orderByItem.setDirection(order);
			
            return orderByItem;
        }
    }

注册OrderItemHandlerMethodArgumentResolver：

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void addFormatters(FormatterRegistry registry) {
       registry.addConverter(new OrderItemHandlerMethodArgumentResolver());
    }
}

这里虽然解决了参数接收的问题，但是Swagger生成的文档参数名还是column和direction。我们需要改成prop和order。

由于OrderByItem是jar包中的类，无法修改源码，所以不能直接使用ApiModelProperty这个注解。

好在Swagger提供了一个“替身”功能，我们需要先定义一个替身类：

@Data
@ApiModel("排序")
public static class OrderRequest {

    @ApiModelProperty("字段名称")
    private String prop;

    @ApiModelProperty("排序方式：descending倒序，ascending：正序")
    private String order;
}

然后使用替身：

@Configuration
public class SwaggerConfig {

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("test")
                .description("test")
                .version("1.0")
                .build();
    }

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .directModelSubstitute(OrderByItem.class, OrderRequest.class);
    }
}