asp.net-web-api - 如何使用 Swashbuckle 实现 OpenAPI readOnly 和 writeOnly

Question

我在 .Net 5.0 Web API 中使用 Swashbuckle (6.1.1)。我仍在学习，但我想实现一个类，其中某些属性仅在使用 GET“阅读”时才有效。 , 以及使用 POST“写入”时的其他属性.根据OpenAPI spec :

You can use the readOnly and writeOnly keywords to mark specific properties as read-only or write-only. This is useful, for example, when GET returns more properties than used in POST – you can use the same schema in both GET and POST and mark the extra properties as readOnly. readOnly properties are included in responses but not in requests, and writeOnly properties may be sent in requests but not in responses.

这正是我想要达到的目标。但是，我正在努力让 Swashbuckle 使用 readOnly 生成 OpenAPI 规范。和 writeOnly关键作品。
例如:

    public class testDetails
    {            
        public string commonProperty { get; set; }           
        public  string readOnlyProperty { get; set; }
        public string writeOnlyProperty {  get; set; }
    }

    [ProducesResponseType(StatusCodes.Status200OK)]    
    [HttpGet("Get")]
    public IActionResult Get([FromQuery] testDetails details)
    {
        Debug.WriteLine($"commonProperty is {details.commonProperty}");
        Debug.WriteLine($"readOnlyProperty is {details.readOnlyProperty}");
        Debug.WriteLine($"writeOnlyProperty is {details.writeOnlyProperty}");
        return Ok();
    }

我要 readOnlyProperty被标记为 readOnly , 和 writeOnlyProperty被标记为 writeOnly在生成的 swagger.json .
实际上，writeOnlyProperty不应作为任何 GET 的属性出现(但会出现在 POST/PUT 中)，相反 readOnlyProperty应该可用于 GET但不是 POST .
我试过添加 System.ComponentModel [ReadOnly ] 属性，但没有效果。我也尝试将访问器更改为

 public class testDetails
    {            
        public string commonProperty { get; set; }           
        public  string readOnlyProperty { get; internal set; }
        public string writeOnlyProperty {  internal get; set; }
    }

...但这最终只会完全隐藏属性。这些都不会影响代码的实际操作，但我仍然希望属性只能在需要的地方写入，否则为只读 - 正如 OpenAPI 规范所描述的那样。有没有办法做到这一点，而无需创建单独的“读写类”？

Answer 1

您可以使用 SwaggerSchemaAttribute 注释只读和只写属性来自包裹Swashbuckle.AspNetCore.Annotations .这将允许您使用 readOnly 生成 OpenAPI 规范。和 writeOnly关键字并从 Swagger UI 隐藏属性。
跟着这些步骤:

将以下 Nuget 包安装到 ASP.NET Core 应用程序中。

Install-Package Swashbuckle.AspNetCore.Annotations

在 ConfigureServices Startup.cs的方法, 在 Swagger 配置块中启用注释:

services.AddSwaggerGen(c =>
{
   ...

   c.EnableAnnotations();
});

为您的模型添加属性:

public class TestDetails
{
    public string CommonProperty { get; set; }

    [SwaggerSchema(ReadOnly = true)]
    public string ReadOnlyProperty { get; set; }

    [SwaggerSchema(WriteOnly = true)]
    public string WriteOnlyProperty { get; set; }
}

您的 Controller 可能如下所示:

[ApiController]
[Route("[controller]")]
public class DataController : ControllerBase
{
    private TestDetails testDetails = new TestDetails()
    {
        CommonProperty = "Common prop value",
        ReadOnlyProperty = "ReadOnly prop value",
        WriteOnlyProperty = "WriteOnly prop value"
    };

    public DataController()
    {
        
    }

    [HttpGet]
    [ProducesResponseType(typeof(TestDetails), (int) HttpStatusCode.OK)]
    public IActionResult Get()
    {
        return Ok(testDetails);
    }

    [HttpPost]
    [ProducesResponseType((int)HttpStatusCode.OK)]
    public IActionResult Post([FromBody] TestDetails details)
    {
        return Ok();
    }
}