c# - 使用 Azure Functions OpenAPI 扩展添加只读属性

Question

我们正在将 Azure Function 应用从 .NET Framework 4.8 迁移到 .NET 6.0。

旧版本在模型属性上使用多个自定义属性来控制生成的 swagger OpenAPI 2.0 文档中显示的内容 - 包括“必需”和“只读”。

例如，当模型同时具有读取/创建操作时生成 swagger 文档时，它使用 readonly 属性来“隐藏”创建时不接受的属性。相同的属性不会在读取调用中隐藏，因为服务器已在此时填充它。

新函数应用使用提供的 Microsoft.Azure.WebJobs.Extensions.OpenApi 扩展来生成 OpenAPI 3.0 文档，我们希望找到一种方法来添加相同的“只读”功能。

有人知道如何做到这一点吗？

旧应用程序的示例模型:

public class ThingModel
{
    [Display(Name = "Thing Id", Description = "Thing Model Id")]
    [ReadOnly(true)]
    public Guid? Id { get; set; }

    [Display(Name = "Thing Name", Description = "Name of Thing")]
    [Attributes.Required(HttpMethodType.Post)]
    public string Name { get; set; }

    [Display(Name = "Thing Description", Description = "Description of Thing")]        
    public string Description { get; set; }
}

nuget 包的文档定义了许多属性，但“readonly”不是其中之一:https://github.com/Azure/azure-functions-openapi-extension/blob/main/docs/openapi-core.md

Answer 1

感谢mnemcik-visma

没有特定字段如 readOnly 。在使用API​​优先方法时，需要使用相同的数据模型作为API调用的输入和输出，显然是为了限制定义的重复。使用 readOnly 属性来指示客户端应用程序不应将其设置为输入字段的字段。

Microsoft.Azure.WebJobs.Extensions.OpenApi 扩展为 Azure Functions 应用生成 OpenAPI 3.0 文档。要添加“readonly”功能，您可以在属性的JSON架构定义中使用“readOnly”属性。

要在 ThingModel 类的 "Id" 属性的 JSON 架构定义中定义 "readOnly" 属性:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "Id": {
      "type": "string",
      "format": "uuid",
      "readOnly": true
    },
    "Name": {
      "type": "string"
    },
    "Description": {
      "type": "string"
    }
  }
}

以下是如何在“ThingModel”类的架构中定义“readOnly”属性的另一个示例:

openapi: 3.0.0
info:
  title: Thing Model API
  version: 1.0.0
paths:
  /thing:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ThingModel'
      responses:
        '200':
          description: Success
components:
  schemas:
    ThingModel:
      type: object
      properties:
        Id:
          type: string
          format: uuid
          readOnly: true
        Name:
          type: string
          required: true
        Description:
          type: string

在此示例中，通过将“readOnly”属性设置为“true”，将“Id”属性定义为只读。

有关properties.的更多信息