Swagger で部品化を促す allOf キーワードについて

Swagger で部品化を促す allOf キーワードについて

こんばんは。七色メガネです。

前回、Swagger.yaml の基本的な書き方について学びました。

今回はその続きで、Swagger.yaml における allOf キーワードの扱いについて学んでいきます。

 

Swagger ってなに?

Swagger とは、RESTful API の作成を補助するオープンソースのフレームワークのことです。
前回の記事で詳しく説明しているので、よろしければご参照ください。

Swagger とその基本書式について学ぶ

 

部品化したスキーマを統合してスキーマを作成する(allOf)

スキーマは便利ですが、何も考えずにスキーマを作り続けていると似たような構成のスキーマがたくさん出来てしまい、DRYに反した冗長なyamlファイルが出来てしまいます。

それを解決するのが、allOf というキーワードで表現できる部品化の考えです。

allOf は、指定したスキーマからプロパティだけを抽出し、自スキーマのプロパティに変換することが出来ます。
つまり、部品として作成しておいたスキーマを allOf で統合するという方法でスキーマを作成すれば、似たような構成のスキーマが乱立することを回避できるわけです。

文法

次の例では、部品スキーマとして heaf プロパティを持つ HumanHeader と、 body プロパティを持つ HumanBody を定義しています。そして allOf で Header と Body を統合したスキーマとして Human を定義しています。

 

UI上のスキーマの情報をみて分かる通り、head と body が抽出され、Human のプロパティになっています。
これで、他のスキーマで head プロパティを使用したい時には、個別に作成するのではなくこの HumanHeader スキーマを部品として使えば良いということになりました。

allOf の記述例

基本型と基本型の統合 ( 意味がないとは思うけど書式の確認として )

スキーマとスキーマの統合

スキーマと基本型の統合

 

 

他の of 系キーワード

他に似ているキーワードとして oneOf / anyOf などがありますが、こちらは Swagger2.0 では使用できず、OpenApi3.0 から使用できるようです。

今回の学習は Swagger2.0 で行なっているので、これらについては割愛します。

 

参考

https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/

Knowledgeカテゴリの最新記事