更改 Swagger/Swashbuckle 導出的屬性類型

Question

我有一個相當復雜的 object 嵌套對象； 請注意，在下面的示例中，我大大簡化了這個 object。

假設以下示例 object：

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 ），但這似乎是不可能的。

此外，由於 object 相當復雜並且來自第三方庫，因此我很難在屬性上實際添加注釋/屬性，因為我無法（輕松）更改 model。

I could resort to AutoMapper (or alike) to create another model with a string for IP adresses but that would mean having to model all objects in the original model. 此外，當 model 發生變化時，它需要額外的代碼和維護。 我寧願以某種方式告訴 Swashbuckle IP 地址（因此， IPAddress類型將表示為字符串（傳入和傳出到我的 API）。我正在尋找有關如何以最佳方式完成此任務的選項可能在給定的限制內（最好不要將新模型引入 map，最好沒有注釋/屬性，因為我無法輕松訪問第 3 方庫）。有沒有辦法為 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 });
            // ...
        });
}

謝謝strict01

Answer 1

當您轉換為非復雜類型時，您應該能夠將MapType用於此 IPAddress 示例：

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

如果要轉換為復雜類型，則需要使用SchemaFilter 。