如何使用 Swashbuckle 实现 OpenAPI readOnly 和 writeOnly

Question

我在 .Net 5.0 Web API 中使用 Swashbuckle (6.1.1)。我还在学习，但我想实现一个 class，其中某些属性仅在 'reading' 和 GET 时有效，而其他属性在 'writing' 和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 和 writeOnly keyworks 的 OpenAPI 规范。

例如：

    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 在生成的 swagger.json 中被标记为 readOnly，writeOnlyProperty 被标记为 writeOnly。

实际上，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; }
    }

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

Answer 1

您可以使用包 Swashbuckle.AspNetCore.Annotations 中的 SwaggerSchemaAttribute 注释只读和只写属性。这将允许您使用 readOnly 和 writeOnly 关键字生成 OpenAPI 规范，还可以从 Swagger UI.

中隐藏属性

按照以下步骤操作：

将以下 Nuget 包安装到您的 ASP.NET 核心应用程序中。

Install-Package Swashbuckle.AspNetCore.Annotations

在 Startup.cs 的 ConfigureServices 方法中，在 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; }
}

您的控制器可能看起来像：

[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();
    }
}

如何使用 Swashbuckle 实现 OpenAPI readOnly 和 writeOnly

How to implement OpenAPI readOnly and writeOnly with Swashbuckle

asp.net-web-api

openapi

swashbuckle