如何在 Open API 规范 3.0 中添加 allof 类型？

Question

我们遵循设计优先的方法来创建 API。

我们想要使用继承的场景之一我无法为其定义规范。

这是它的 C# 类型

public class PublishRequest
    {

        [JsonProperty("notificationType")]
        public string NotificationType { get; set; }

        [JsonProperty("source")]
        public string Source { get; set; }

        [JsonProperty("timestamp")]
        public string Timestamp { get; set; }

        [JsonProperty("payload")]
        public List<BaseObject> Payload { get; set; }
    }

此 class 有一个属性用于 BaseObject

 public class BaseObject
    {
        [JsonProperty("Id")]
        public string Id { get; set; }
    }

所有其他类型都继承自该类型，如下所示：

public class Accounts:BaseObject
    {
        [JsonProperty("phone")]
        public string Phone { get; set; }
        [JsonProperty("accountid")]
        public string AccountID { get; set; }
        [JsonProperty("name")]
        public string Name { get; set; }
        [JsonProperty("legalname")]
        public string LegalName { get; set; }
        [JsonProperty("website")]
        public string Website { get; set; }
        [JsonProperty("linkedin")]
        public string LinkedIn { get; set; }
        [JsonProperty("twitter")]
        public string Twitter { get; set; }
    }

使用这些 classes 的规范是这样的：

/notification/publish:
    post:
      summary: publish notification
      tags:
        - Notification
      requestBody:
        description: publish request body
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishRequest'
      responses:
        "200":
          description: success message

我面临的问题是为其定义架构。

架构如下所示

PublishRequest:
      required:
        - notificationType
      properties:
        notificationType:
          type: string 
          enum: [account_created, account_updated]
        source:
          type: string 
          enum: [A, B]
        timestamp:
          type: string 
          format: date-time          
        payload: 
          $ref: "#/components/schemas/NotificationPayload"

    NotificationPayload:
      type: array
      items:
        oneOf:
          - $ref: "#/components/schemas/Account"        

    BaseObject:
      properties:
        Id:
          type: string
    Account:
     allOf:    
      $ref: '#/components/schemas/BaseObject'
      type: object
      properties:
        phone:
          type: string
        accountId:
          type: string
        name:
          type: string
        legalname:
          type: string  
        website:
          type: string
        linkedin:
          type: string
        twitter:
          type: string
        facebook:
          type: string
        defaultcurrency:
          type: string

我在 swagger 编辑器中不断收到此错误

Structural error at components.schemas.Account.allOf
should be array

Answer 1

allOf 的正确语法如下。 allOf 采用 list 子模式，因此每个子模式必须在 YAML 中以 - 为前缀。

    Account:
      allOf:
        - $ref: '#/components/schemas/BaseObject'
        - type: object
          properties:
            phone:
              type: string
            ...

其他几件事：

在NotificationPayload中，items不需要oneOf，因为只有一个子模式。

    NotificationPayload:
      type: array
      items:
        $ref: "#/components/schemas/Account"

记得将 type: object 添加到对象模式，在本例中 - PublishRequest 和 BaseObject。仅properties关键字不足以表示对象类型，实际上表示"any type".

如何在 Open API 规范 3.0 中添加 allof 类型？

How to add allof type in Open API Specification 3.0?

c#

api-design

swagger

openapi