APIGit
2024-03-15
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 のデータ コントラクトが明確かつ堅牢になります。
© 2024 APIGit Inc.