关于java:自定义SpringBootSwagger中ApiModel默认名称

前言

我的项目应用的 springfox-swagger2@2.9.2 版本

在 Spring 中集成 swagger 文档性能，须要通过 @ApiModel 注解润饰出入参的类，然而如果有两个不同包下的雷同名称的类都应用了 @ApiModel 注解时，会导致文档被笼罩，例如：

• com.example.demo.login.dto.UserDTO

package com.example.demo.login.dto;

@Data
@ApiModel
public class UserDTO{@ApiModelProperty("姓名")
  private String name;
  @ApiModelProperty("年龄")
  private Integer age;
}

• com.example.demo.vip.dto.UserDTO

package com.example.demo.vip.dto;

@Data
@ApiModel
public class UserDTO{@ApiModelProperty("姓名")
  private String name;
  @ApiModelProperty("会员级别")
  private Integer vipLevel;
}

下面两个类生成进去的文档会变成一个swagger model：

从而导致接口文档显示谬误：

解决抵触

批改 @ApiModel 注解（举荐）

通过批改 @ApiModel 的 value 属性，来躲避同名抵触，批改之后为：

package com.example.demo.login.dto;

@Data
@ApiModel("login$UserDTO")
public class UserDTO{}

package com.example.demo.vip.dto;

@Data
@ApiModel("vip$UserDTO")
public class UserDTO{}

能够看到生成了两个swagger model：

批改类名

把两个类名做批改，让类名不抵触即可。

自定义 swagger 插件

然而下面解决抵触的形式还是太麻烦了，定义一个文档的出入参类而已，还要思考类重名的问题，这种减少心智累赘和工作量的问题应该要尽量避免掉的，我在想有没有可能做到每个类上只须要加上 @ApiModel 注解就行，剩下的抵触问题全副不必思考。

于是乎通过跟踪源码，找到了 swagger model 名称生成的中央，详见：github

能够看到取名的逻辑是，优先取 @ApiModel 的value值，如果没有就会应用 defaultTypeName, 跟进去一看，defaultTypeName 是间接取类的 简称，代码如下：

正是因为默认状况下取类的 简称 ，导致不同包名下的同名类生成进去的swagger model 被笼罩。
起因曾经剖析进去了，接下来其实就是看看能不能定制化这个 super.nameFor(type) 办法了，然而很遗憾这个办法是写死的，没中央下手，然而 ApiModelTypeNameProvider 这个类上两个注解 @Component 和@Order曾经明示了这个是一个Spring bean，并且是通过Spring 插件机制进行加载的，所以能够自定义一个插件来实现，在默认时通过残缺的类门路和类名来生成惟一的swagger model，代码如下：

@Component
@Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER - 100)
public class FullPathTypeNameProvider extends DefaultTypeNameProvider {

    public static final String SPLIT_CHAR = "$";

    @Override
    public String nameFor(Class<?> type) {ApiModel annotation = AnnotationUtils.findAnnotation(type, ApiModel.class);
        if (annotation == null) {return super.nameFor(type);
        }
        if (StringUtils.hasText(annotation.value())) {return annotation.value();
        }
        // 如果 @ApiModel 的 value 为空，则默认取残缺类门路
        int packagePathLength = type.getPackage().getName().length();
        return Stream.of(type.getPackage().getName().split("\\."))
                .map(path -> path.substring(0, 1))
                .collect(Collectors.joining(SPLIT_CHAR))
                + SPLIT_CHAR
                + type.getName().substring(packagePathLength + 1);
    }

}

成果如下：

后记

通过这一个小小的优化，就能够缩小许多团队中不必要的沟通老本，让咱们能更专一于业务开发。

我是 MonkeyWie，欢送扫码👇👇关注！不定期在公众号中分享JAVA、Golang、 前端 、docker、k8s 等干货常识。