前言

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

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

  • com.example.demo.login.dto.UserDTO
package com.example.demo.login.dto;@Data@ApiModelpublic class UserDTO{  @ApiModelProperty("姓名")  private String name;  @ApiModelProperty("年龄")  private Integer age;}
  • com.example.demo.vip.dto.UserDTO
package com.example.demo.vip.dto;@Data@ApiModelpublic 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等干货常识。