将属性类型更改为 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(...)方法中的转换器'registered'。这很好 [=70=] 结果为：

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

反之亦然，我的控制器 "understands" 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）。我正在寻找选项关于如何在给定限制内以最佳方式完成此操作（最好不要引入要映射到的新模型，最好不要 annotations/attributes 因为我无法轻松访问第 3 方库）。有没有办法注册 "type-converter-something" 让 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 用于此 IP 地址示例：

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

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

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

Change property type as exported by Swagger/Swashbuckle

c#

swagger

.net-core

swashbuckle

更新：！

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

Change property type as exported by Swagger/Swashbuckle

c#

swagger

.net-core

swashbuckle

更新：！

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