OpenAPI 仕様 (OAS) を使用して API を設計または文書化する場合、複雑なデータ構造を記述する必要が生じることがよくあります。これらの構造では、条件ごとに異なるオブジェクト構造、複数のオブジェクトを 1 つに組み合わせる、オブジェクトが複数のタイプのいずれか 1 つに一致することを指定するなど、さまざまなシナリオの定義が必要になる場合があります。ここがoneOf、allOf、 そしてanyOf Shine は、これらのタスクに必要な柔軟性と精度を提供します。

理解allOf

allOf は、複数のスキーマを、結合されたスキーマのすべてのプロパティを含む 1 つのスキーマに結合するために使用されます。これは、他のいくつかのスキーマからプロパティを継承する複雑なスキーマを作成する場合に特に便利です。

たとえば、Person のような共通プロパティを持つスキーマname そしてage、そしてStudent すべてのプロパティを含むスキーマPerson より多いstudentId、使用できますallOf を作成するにはStudent を繰り返さずにスキーマを作成するPerson プロパティ。

components:
  schemas:
    Person:
      type: object
      properties:
        name:
          type: string
        age:
          type: integer
    Student:
      allOf:
        - $ref: '#/components/schemas/Person'
        - type: object
          properties:
            studentId:
              type: string

探検するoneOf

oneOf データが参照されるスキーマの 1 つと正確に一致する必要があることを指定します。これは、特定のインスタンスに対して 1 つの構造のみが有効な、データ オブジェクトのさまざまな構造を定義する場合に便利です。

支払い方法として、クレジット カードまたは銀行口座のいずれかを受け入れる API エンドポイントを考えてみましょう。両方を受け入れることはできません。使用するoneOfでは、これらのオプションを明確に定義できます。

components:
  schemas:
    CreditCard:
      type: object
      properties:
        number:
          type: string
        expiryDate:
          type: string
        cvv:
          type: string
    BankAccount:
      type: object
      properties:
        accountNumber:
          type: string
        routingNumber:
          type: string
    PaymentMethod:
      oneOf:
        - $ref: '#/components/schemas/CreditCard'
        - $ref: '#/components/schemas/BankAccount'

解読anyOf

anyOf データが参照されたスキーマのいずれか (1 つ以上) と一致するようにします。データが複数の形式である場合に柔軟性が提供され、データのような排他性は必要ありません。oneOf。

たとえば、API エンドポイントがcontact オブジェクトは次のいずれかになりますphone number、email address、または両方を使用できます。anyOf これを表すには:

components:
  schemas:
    PhoneNumber:
      type: object
      properties:
        phone:
          type: string
    EmailAddress:
      type: object
      properties:
        email:
          type: string
    Contact:
      anyOf:
        - $ref: '#/components/schemas/PhoneNumber'
        - $ref: '#/components/schemas/EmailAddress'

結論

のallOf、oneOf、 そしてanyOf キーワードは OpenAPI 仕様に本質的な汎用性を追加し、複雑で微妙なデータ モデルの定義を可能にします。これらのツールを理解し、効果的に使用することで、API 設計者と文書作成者は、より正確で柔軟な API 仕様を作成できます。プロパティの継承、排他的な型の指定、または複数の構造の許可のいずれを行う場合でも、これらのキーワードにより、API のデータ コントラクトが明確かつ堅牢になります。