更改 Swagger/Swashbuckle 导出的属性类型

Question

我有一个带有嵌套对象的相当复杂的对象；请注意，在下面的示例中，我大大简化了这个对象。

假设以下示例对象：

public class Result {
    public string Name { get; set; }
    public IpAddress IpAddress { get; set; }
}

我已经实现了一个JsonConverter<IPAddress>比（反）序列化 Ip 作为一个字符串：

public class IPAddressConverter : JsonConverter<IPAddress>
{
    public override IPAddress Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
        => IPAddress.Parse(reader.GetString());

    public override void Write(Utf8JsonWriter writer, IPAddress value, JsonSerializerOptions options)
        => writer.WriteStringValue(value.ToString());
}

所述IPAddressConverter然后“注册”作为在一个转换器AddJsonOptions(...)的方法。这很好地返回结果为：

{ "Name": "Foo", "IpAddress": "198.51.100.1" }

并且，反之亦然，我的控制器“理解”指定为字符串的 IP 地址：

public IEnumerable<Result> FindByIp(IpAddress ip) {
    // ...
}

但是，SwashBuckle 将其导出为：

public class Result {
    public string Name { get; set; }
    public IpAddress IpAddress { get; set; }
}

对于更倾向于视觉的人来说，它看起来像：

然而，我想要实现的是：

{
  "openapi": "3.0.1",
  "info": {
    "title": "Example",
    "version": "v1"
  },
  "paths": {
    "/FindByIp": {
      "get": {
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": {
                    "$ref": "#/components/schemas/Result"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Result": {
        "type": "object",
        "properties": {
          "ip": {
            "type": "string",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      }
    }
  }
}

再次，可视化：

我希望能够在某些属性上添加注释/属性（所以我查看了Swashbuckle.AspNetCore.Annotations），但这似乎不可能。

此外，因为该对象相当复杂并且来自第 3 方库，所以我很难在属性上实际添加注释/属性，因为我无法（轻松）更改模型。

我可以求助于 AutoMapper（或类似的）来创建另一个带有 IP 地址字符串的模型，但这意味着必须对原始模型中的所有对象进行建模。此外，当模型更改时，它需要额外的代码和维护。我宁愿告诉 Swashbuckle，不知何故，IP 地址（因此，类型IPAddress将表示为一个字符串（传入和传出到我的 API）。我正在寻找有关如何以最佳方式完成此任务的选项在给定的限制内（最好不引入要映射的新模型，最好没有注释/属性，因为我无法轻松访问 3rd 方库）。有没有办法为 Swashbuckle 注册“类型转换器”来处理这个问题?

更新：解决了！

这就是我最终的结果：

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    services
        .AddResponseCompression()
        .AddMemoryCache()
        .AddControllers()
        // etc...
        // etc...

    // Here's the interesting part:
    services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new OpenApiInfo { Title = "Example", Version = "v1" });
            c.MapType<IPAddress>(() => new OpenApiSchema { Type = typeof(string).Name });
            // ...
        });
}

谢谢strickt01

Answer 1

当您转换为非复杂类型时，您应该能够使用MapType此 IPAddress 示例：

swagger.MapType<IPAddress>(() => new Schema { Type = "string" });

如果要转换为复杂类型，则需要使用SchemaFilter。