Springfox 2.9.2下Swagger继承模型未生成关联POJO定义问题

1. Inconsistency 模型缺失的核心原因 #

springfox 2.9.2 的模型扫描逻辑本身有明显缺陷：

• 它只会主动扫描两类模型：一类是接口方法签名上直接声明的参数/返回值类型，另一类是沿着已经被纳入扫描范围的模型类字段，递归向下遍历引用的类。
• 你的场景里接口直接声明的参数类型是抽象父类AbstractPolicyUpdate，springfox从父类出发做字段扫描时，只会拿到父类自己的两个字段（clientId、status），不会顺着抽象类上@ApiModel标注的subTypes数组去扫描两个子类的内容；
• 哪怕后续springfox碰巧通过某种逻辑加载到了两个子类的schema，它在处理SuccessPolicyUpdate的inconsistencies字段时，因为自身缓存逻辑的问题，也没有正确触发对Inconsistency类的扫描加载，最终Inconsistency的引用留在了JSON里，定义却根本没被写入definitions节点。

2. 继承结构生成异常的原因 #

你现在看到的子类schema块里，把父类的clientId、status字段重复列了一遍，完全是springfox 2.9.2 的已知实现缺陷：

• 符合Swagger 2.0规范的多态结构，应该是子类通过allOf引用父类schema，自身的schema块里只保留子类独有的字段，完全不重复父类已经定义过的内容。
• springfox 2.9.2 在解析带@ApiModel(parent = 父类.class)注解的子类时，没有做父类字段的去重处理，会把父类的所有字段原样拷贝一份到子类的独立schema块里，造成字段冗余。
• 更关键的是，因为没有正确建立父类discriminator和子类的映射，现在生成的AbstractPolicyUpdate schema里根本没有提示可选的子类型，Swagger UI拿到这个JSON后，完全没法渲染正确的多态请求结构，用户填参数时根本看不到两个子类对应的专属字段。

• 调整Docket配置，显式把所有关联模型加入扫描范围，解决漏扫问题：

  @Bean
  public Docket policyApi() {
      return new Docket(DocumentationType.SWAGGER_2)
              .select()
              .apis(RequestHandlerSelectors.basePackage("你的业务代码包路径"))
              .paths(PathSelectors.any())
              .build()
              // 强制要求springfox加载这些类的模型定义，避免递归引用断链
              .additionalModels(typeResolver.resolve(
                      SuccessPolicyUpdate.class,
                      FailurePolicyUpdate.class,
                      Inconsistency.class
              ));
  }
  

• 删除两个子类上多余的@ApiModel(parent = AbstractPolicyUpdate.class)注解：springfox 2.9.2 会自动基于抽象类上标注的subTypes数组识别继承关系，重复标注parent属性会直接触发字段重复拷贝的bug。
• 保留抽象类上的多态配置：@ApiModel(discriminator = "status", subTypes = {SuccessPolicyUpdate.class, FailurePolicyUpdate.class})不需要改动，去掉子类的冗余parent注解后，springfox会自动把两个子类的schema关联到父类的discriminator枚举上，形成符合规范的多态结构。
• 修复后的预期效果：
  • definitions节点里会出现完整的Inconsistency schema定义，包含code、oldValue、newValue三个字段
  • 两个子类的allOf块里，只会保留自身独有的字段（FailurePolicyUpdate的code枚举、SuccessPolicyUpdate的policyNumber字符串和inconsistencies数组），不会再重复罗列父类的clientId、status字段
  • 父类的discriminator配置会正确关联两个子类的类型提示，Swagger UI可以正常展示根据status值切换的不同请求结构。

内容的提问来源于stack exchange，提问作者dendimiiii