在NSwag中解析OpenAPI规范的嵌套外部$ref引用问题

问题场景 #

在.NET环境中使用NSwag从OpenAPI 3.0.1规范生成C#客户端时，遇到外部组件引用（尤其是嵌套模式）无法解析的问题，报错：

System.InvalidOperationException: Could not resolve the path '#/components/schemas/SomeSchema'

已确认文件路径相对于NSwag执行位置正确，简单外部引用可正常工作，但包含嵌套引用的模式会解析失败。

引用格式示例：

components:
  schemas:
    SomeSchema:
      $ref: './external_definitions.yml#/components/schemas/SomeSchema'

嵌套模式定义示例（SomeSchema包含多层内部引用）：

SomeSchema:
  type: object
  properties:
    Version:
      type: integer
      nullable: true
    Identifier:
      $ref: '#/components/schemas/UniqueIdentifier'
      nullable: true
    Status:
      $ref: '#/components/schemas/StatusType'
      nullable: true
    Calculations:
      type: array
      items:
        $ref: '#/components/schemas/CalculationType'
      nullable: true
    # 其他嵌套引用属性...
    DeploymentMetadata:
      $ref: '#/components/schemas/DeploymentMetadataType'
      nullable: true

尝试将共享组件提取到单独的data.yml文件，内部引用改为带文件路径的格式（如$ref: './data.yml#/components/schemas/UniqueIdentifier'），但仍存在深层嵌套属性解析失败的情况。

问题根源 #

经排查，该问题大概率源于NSwag依赖的NJsonSchema库对深层嵌套外部引用的解析逻辑存在缺陷，涉及相对路径处理、多层嵌套引用递归解析等场景的已知问题。

可行解决方案 #

1. 预合并OpenAPI规范 #

使用OpenAPI工具链（如OpenAPI CLI）将所有分散的规范文件合并为一个完整的文件，再交给NSwag处理：

openapi bundle main.yml -o bundled.yml

合并后的文件消除了外部引用，NSwag可以正常解析所有嵌套模式。

2. 调整引用策略 #

• 对于共享组件内部的嵌套引用，直接使用主规范中的绝对路径（或合并后的结构路径），避免多层相对路径引用。
• 临时将无法解析的深层嵌套模式复制到主规范中，减少外部引用层级。

3. 升级依赖版本 #

检查NSwag和NJsonSchema的最新版本，部分旧版本的引用解析Bug已在后续更新中修复，升级后可能解决问题。

4. 自定义编程式解析 #

如果使用NSwag的编程式API生成客户端，可以自定义JsonSchemaResolver，手动加载并解析所有依赖的外部Schema文件，补充NSwag默认解析逻辑的不足。

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