在 SwaggerUI 中将记录 JSON 转换为“字符串”

Question

我有一个实现字符串转换的

record

：

[JsonConverter(typeof(ExamplePropJsonConverter))]
public record ExampleProp
{
    private string? Value { get; init; }
    
    public static implicit operator string(ExampleProp value) => value.Value ?? throw new ArgumentNullException();
    public static implicit operator ExampleProp(string value) => new ExampleProp() { Value = value };
    public override string ToString() => (string)this;
}

public class ExamplePropJsonConverter : JsonConverter<ExampleProp>
{
    public override ExampleProp Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) =>
        reader.GetString() ?? throw new ArgumentNullException();
    public override void Write(Utf8JsonWriter writer, ExampleProp value, JsonSerializerOptions options) => 
        writer.WriteStringValue(value);
}

我希望它能够在 API 中以普通字符串的方式简单地表示 JSON。

我有控制器：

[HttpPost("/ep-test")]
public IResult TestEP([FromBody] ExampleProp ep) => Results.Json(ep);

[HttpPost("/string-test")]
public IResult TestString([FromBody] string s) => Results.Json(s);

[HttpPost("/string-as-ep-test")]
public IResult TestStringAsEP([FromBody] string s) => Results.Json((ExampleProp)s);

除了 SwaggerUI 之外，它工作正常：

在 SwaggerUI 中我看到：

• /ep-test
  示例值：

  {}

  
  架构：

  ExampleProp:{}

我希望看到像 url 这样的方案，或者至少是字符串：

• /ep-test
  示例值：

  "string"

  
  架构：

  ExampleProp: string

• /ep-test
  示例值：

  "examplePropFormat"

  
  架构：

  ExampleProp: string($exampleProp)

我预计可能会缺少一些神奇的属性，例如

[JsonConvertAs(typeof(string))]

，它们可能会丢弃显式转换器实现并告诉 Swagger 将类型解释为字符串。

Answer 1

您应该将这些行添加到您的

Program.cs

：

builder.Services.AddSwaggerGen(o =>
{
    o.MapType<ExampleProp>(() => new OpenApiSchema { Type = "string" });
});

更多信息：https://github.com/domaindrivendev/Swashbuckle.AspNetCore#override-schema-for-specific-types