c# - 更改由 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" }

反之亦然，我的 Controller “理解”指定为字符串的 IP 地址:

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

但是，SwashBuckle 将其导出为:

{
  "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": {
      "AddressFamily": {
        "enum": [
          0,
          1,
          2,
          3,
          4,
          5,
          6,
          6,
          7,
          7,
          8,
          9,
          10,
          11,
          12,
          13,
          14,
          15,
          16,
          17,
          18,
          19,
          21,
          22,
          23,
          24,
          25,
          26,
          28,
          29,
          65536,
          65537,
          -1
        ],
        "type": "integer",
        "format": "int32"
      },
      "IPAddress": {
        "type": "object",
        "properties": {
          "addressFamily": {
            "$ref": "#/components/schemas/AddressFamily"
          },
          "scopeId": {
            "type": "integer",
            "format": "int64"
          },
          "isIPv6Multicast": {
            "type": "boolean",
            "readOnly": true
          },
          "isIPv6LinkLocal": {
            "type": "boolean",
            "readOnly": true
          },
          "isIPv6SiteLocal": {
            "type": "boolean",
            "readOnly": true
          },
          "isIPv6Teredo": {
            "type": "boolean",
            "readOnly": true
          },
          "isIPv4MappedToIPv6": {
            "type": "boolean",
            "readOnly": true
          },
          "address": {
            "type": "integer",
            "format": "int64"
          }
        },
        "additionalProperties": false
      },
      "Result": {
        "type": "object",
        "properties": {
          "ip": {
            "$ref": "#/components/schemas/IPAddress"
          },
          "name": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      }
    }
  }
}

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

然而，我想要实现的是:

{
  "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)。我正在寻找有关如何完成此操作的选项在给定限制内可能的最佳方式(最好不要引入要映射到的新模型，最好不要注释/属性，因为我无法轻松访问第 3 方库)。有没有办法为 Swashbuckle 注册“类型转换器”处理这个？

更新:Solved !

这是我最终得到的:

// 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

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

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

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