如何在ASP.NET Core 2.0中借助Swashbuckle使用远程定义？

没问题，我来一步步教你实现需求——让swagger.json的definitions里生成指向远程JSON Schema的$ref格式定义。核心思路是通过自定义文档过滤器修改Swashbuckle生成的Swagger文档结构，下面是具体步骤：

1. 确认Swashbuckle版本适配 #

因为你用的是ASP.NET Core 2.0，需要安装对应版本的Swashbuckle.AspNetCore（2.x系列，比如2.5.0）。如果还没安装，通过NuGet包管理器或命令行安装：

Install-Package Swashbuckle.AspNetCore -Version 2.5.0

2. 创建自定义文档过滤器 #

创建一个实现IDocumentFilter接口的类，它会在Swagger文档生成时注入我们需要的远程引用定义。

基础版（单个远程引用） #

如果只需要添加response这一个远程引用，用这个简单版本：

using Swashbuckle.AspNetCore.Swagger;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Collections.Generic;

public class RemoteSchemaDocumentFilter : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
    {
        // 往swagger文档的definitions里添加远程引用
        swaggerDoc.Definitions["response"] = new SwaggerSchema
        {
            // 通过ExtensionData直接注入$ref属性，确保生成符合要求的JSON结构
            ExtensionData = new Dictionary<string, object>
            {
                { "$ref", "https://localhost/domains/jsonschema#/definitions/response" }
            }
        };
    }
}

进阶版（批量导入本地Schema生成远程引用） #

如果你有本地JSON Schema文件，想批量把里面的定义映射为远程引用，可以用这个版本：

using Swashbuckle.AspNetCore.Swagger;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Collections.Generic;
using System.IO;
using Newtonsoft.Json.Linq;

public class RemoteSchemaDocumentFilter : IDocumentFilter
{
    private readonly string _localSchemaFilePath;
    private readonly string _remoteSchemaBaseUrl;

    // 构造函数传入本地Schema路径和远程Schema的基础URL
    public RemoteSchemaDocumentFilter(string localSchemaFilePath, string remoteSchemaBaseUrl)
    {
        _localSchemaFilePath = localSchemaFilePath;
        _remoteSchemaBaseUrl = remoteSchemaBaseUrl;
    }

    public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
    {
        // 读取本地JSON Schema文件
        var schemaContent = File.ReadAllText(_localSchemaFilePath);
        var schemaObject = JObject.Parse(schemaContent);

        // 获取Schema里的definitions节点
        var localDefinitions = schemaObject["definitions"] as JObject;
        if (localDefinitions == null) return;

        // 遍历所有本地定义，生成对应的远程引用
        foreach (var definition in localDefinitions.Properties())
        {
            swaggerDoc.Definitions[definition.Name] = new SwaggerSchema
            {
                ExtensionData = new Dictionary<string, object>
                {
                    { "$ref", $"{_remoteSchemaBaseUrl}#/definitions/{definition.Name}" }
                }
            };
        }
    }
}

3. 在Startup中注册过滤器 #

打开Startup.cs，在ConfigureServices方法里配置SwaggerGen时，添加我们的自定义过滤器：

对应基础版的注册 #

using Swashbuckle.AspNetCore.Swagger;

public void ConfigureServices(IServiceCollection services)
{
    // 其他服务注册...

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info { Title = "你的API名称", Version = "v1" });
        // 添加自定义文档过滤器
        c.DocumentFilter<RemoteSchemaDocumentFilter>();
    });
}

对应进阶版的注册 #

using Swashbuckle.AspNetCore.Swagger;
using System.IO;

public void ConfigureServices(IServiceCollection services)
{
    // 其他服务注册...

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info { Title = "你的API名称", Version = "v1" });
        // 注册过滤器，传入本地Schema路径和远程基础URL
        c.DocumentFilter<RemoteSchemaDocumentFilter>(
            Path.Combine(Directory.GetCurrentDirectory(), "schemas", "你的Schema文件名.json"),
            "https://localhost/domains/jsonschema"
        );
    });
}

4. 验证效果 #

启动你的API项目，访问Swagger文档的JSON地址（比如https://localhost:5001/swagger/v1/swagger.json），你会看到definitions里已经生成了符合要求的结构：

"definitions": {
  "response": {
    "$ref": "https://localhost/domains/jsonschema#/definitions/response"
  }
}

注意事项 #

• 如果你的API中已经存在同名的定义（比如response），过滤器会覆盖它，所以要注意避免命名冲突。
• 确保远程JSON Schema的URL是可访问的，这样Swagger UI才能正常加载并解析引用的定义。

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