Swagger Core 中 OpenAPI 3.1 数组类型的内联模式解析问题解析

问题背景

在 Swagger Core 项目中，开发者在使用 OpenAPI 3.1 规范时遇到了一个关于数组类型内联模式解析的问题。具体表现为：当尝试解析数组类型的对象（如 CustomObject[] 或 List）时，即使设置了 SchemaResolution.INLINE 模式，生成的 Schema 仍然会包含引用（$ref）而不是完全内联的对象定义。

问题复现

通过以下代码可以复现该问题：

ModelResolver resolver = new ModelResolver(mapper).openapi31(true);
resolver.setSchemaResolution(SchemaResolution.INLINE);
context = new ModelConverterContextImpl(resolver);
context.resolve(new AnnotatedType().type(CustomObject[].class));

期望的输出是完全内联的数组定义：

{
  "items": {
    "type": "object",
    "properties": {
      "...": "..."
    }
  },
  "type": "array"
}

但实际得到的却是包含引用的数组定义：

{
  "items": {
    "$ref": "#/components/schemas/CustomObject"
  },
  "type": "array"
}

技术分析

SchemaResolution 机制

SchemaResolution 是 Swagger Core 提供的一个机制，用于控制如何解析和生成 Schema 定义。它主要有两种模式：

1. SCHEMA：默认模式，会生成引用（$ref）指向组件部分定义的 Schema
2. INLINE：内联模式，直接将对象定义内联到使用位置

OpenAPI 3.1 的特殊性

在 OpenAPI 3.1 规范中，SchemaResolution 机制的行为有所变化。根据项目文档，SchemaResolution 原本是为 OpenAPI 3.0 规范设计的，在 3.1 规范中默认不会应用这一机制。

解决方案

项目维护者通过 PR #4784 修复了这个问题，并引入了一个新的系统属性 apply-schema-resolution 来控制是否在 OpenAPI 3.1 规范中应用 SchemaResolution 机制。

开发者可以通过以下方式启用这一功能：

1. 设置系统属性：System.setProperty("apply-schema-resolution", "true")
2. 设置环境变量：APPLY_SCHEMA_RESOLUTION=true

最佳实践建议

1. 明确规范版本：在使用前明确指定 OpenAPI 版本，避免版本混淆导致的行为差异
2. 谨慎使用内联模式：虽然内联模式可以减少引用，但可能导致文档体积增大
3. 考虑向后兼容：如果项目需要同时支持 3.0 和 3.1 规范，建议进行充分的测试

未来改进方向

1. 提供更灵活的配置方式，如通过方法调用而非系统属性来控制解析行为
2. 完善文档，明确说明不同 OpenAPI 版本下 SchemaResolution 的行为差异
3. 考虑为 OpenAPI 3.1 设计专门的解析策略

这个问题展示了 API 文档生成工具在处理不同规范版本时的复杂性，也提醒开发者在升级规范版本时需要注意行为变化。