在 ASP.NET Core 3.0 Swagger 中将字符串标记为不可为空

Question

我正在使用 ASP.NET Core 3 和 Swashbuckle，大部分是默认配置，我有一个 DTO 参数，上面有一个我希望不可为空的字符串。我怎样才能做到这一点？请注意，在 Swagger 中，Required 和 nullability 是不同的关注点。

它还使用 C#8 和不可为空的东西，因此编译器应该已经将属性注释为不可为空。可以理解的是，Swashbuckle 尚未更新以考虑到这一点（也许不能），但我希望能够以某种方式覆盖生成的元数据。

class MyDto {
    [Required]
    // I want this to show as non-nullable in the swagger documentation (and ideally also be non-nullable in the binding)
    public string TestProp { get; set; }
}

[HttpPost]
public void Post([FromBody] MyDto requestModel) {
}

我试过让它成为必需的。我还尝试添加 Newtonsoft 注释，但这些注释似乎都没有。

生成的 Swagger 文档的相关位：

    "MyDto": {
      "required": [
        "testProp"
      ],
      "type": "object",
      "properties": {
        "testProp": {
          "type": "string",
          "nullable": true
        }
      },
      "additionalProperties": false
     }

请注意，将字符串参数直接作为参数不会生成可为空的属性。例如

[HttpPost("testPost")]
public void Post([FromBody] [Required] string testProp) {
}

会产生

"/api/test/testPost": {
  "post": {
    "tags": [
      "Test"
    ],
    "requestBody": {
      "content": {
        "application/json": {
          "schema": {
            "type": "string"
          }
        },
        "text/json": {
          "schema": {
            "type": "string"
          }
        },
        "application/*+json": {
          "schema": {
            "type": "string"
          }
        }
      },
      "required": true
    },
    "responses": {
      "200": {
        "description": "Success"
      }
    }
  }
},

Answer 1

您现在可以使用可为 null 的引用类型将字符串标记为可选或必需：

• 为您的项目/解决方案启用可为空的引用类型

• 将 Dtos 中的字符串标记为可为空：

  public class ExampleDto
  {
     [StringLength(64, MinimumLength = 4)]
     public string RequiredString { get; set; }
  
     [StringLength(200)]
     public string? OptionalString { get; set; }
  }
  

• 在您的中启用 Swagger 支持Startup.cs

  services.AddSwaggerGen(options =>
  {
      options.SupportNonNullableReferenceTypes();
  });
  

这导致：

{
  "Example": {
    "type": "object",
    "properties": {
      "requiredString": {
        "maxLength": 64,
        "minLength": 4,
        "type": "string"
      },
      "optionalString": {
        "maxLength": 200,
        "minLength": 0,
        "type": "string",
        "nullable": true
      }
    },
    "additionalProperties": false
  }
}

Answer 2

直到nullable:true为可选字符串发出v4.01 。这在第一个 5.0 RC 版本中nullable:true被破坏，并且根本没有为可选字符串发出。这显然是错误的。

从 5.0 RC3 开始，可选字符串再次可以为空。

要指定可选字符串不可为空，您需要添加[JsonProperty(Required = Required.DisallowNull)]到属性中。从Swashbuckle 的单元测试之一复制，这个：

    [JsonProperty(Required = Required.DisallowNull)]
    public string StringWithRequiredDisallowNull { get; set; }

应该设置属性的 Nullable 标志：

Assert.False(schema.Properties["StringWithRequiredDisallowNull"].Nullable);

并发出nullable:true。