Swagger におけるスキーマの定義や配列表現について

Swagger におけるスキーマの定義や配列表現について

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

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

今回はその続きで、Swagger.yaml におけるスキーマの定義方法と配列の扱いについて学んでいきます。

 

Swagger ってなに?

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

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

スキーマの定義

スキーマとは、個々のモデルデータの定義です。

definitions という階層下で定義した各ブロックがスキーマとしてyaml上で認識されます。
definitions は path と同じ階層、つまり最上位階層に配置します。

スキーマのサンプル表現

各モデルには example ブロックを設定することで、サンプルデータを設定することができます。
このサンプルデータは、スキーマが参照される時に表示されます。

 

pathブロックからのスキーマ参照

定義したスキーマは、pathブロックからは $ref という表記で参照することができます。モデルにサンプルデータを設定していた場合、このタイミングで表示されます。

文法

次の例では、GETに対するハンドラの 200 レスポンスで返却するデータとして、先ほど定義した Megane を指定しています。
レスポンスだけではなく、パラメータでも同様にスキーマを参照することができます。

 

スキーマのプロパティの配列表現

スキーマが保持するプロパティについて、配列を表現できます。

文法

 

ここでは、 Megane スキーマにおける madeBy というプロパティについて、 string の配列 で在ることを定義しています。

 

スキーマ配列の表現

スキーマ・プロパティにおける string やinteger の配列は、先ほどの方法で表現できます。
次に、スキーマそのものを配列として扱う方法に触れます。

方法は2つあります。1つは、スキーマを参照する時に配列として読み込む方法、もう一つは、スキーマ配列をプロパティとして持つスキーマを定義する方法です。

スキーマを配列として参照する

こちらの方法は、スキーマ定義側ではなく参照する側から配列を指定するものです。

文法

 

次の例で使用するスキーマは先ほどと同様の Megane です。スキーマを参照している ref 部分に注目してください。
先ほどは type を指定せず ref していたので単一のスキーマが取得できていましたが、今回は type: array を指定しています。そして配列の中身として Megane を指定することで、 Megane を配列 を表現しています。

注意するのは、 type: array と items: は同一階層レベルに配置するということです。items を一階層深くしてしまうとエラーとなります。

UI上の配列表現はちょっと見にくいのですが、 { } で表現される単一スキーマを囲むように [ ] が配置されており、スキーマの配列であることが表現されています。

スキーマを配列で保持するスキーマを定義する

もう一つの方法は、スキーマのプロパティでスキーマの配列を保持してしまうものです。
これは非スキーマ時の書き方と同じですね。

文法

次の例では2つのスキーマが定義されています。

1つは、先ほどから使用している Megane スキーマです。
もう1つは、 Megane スキーマを配列としてプロパティに保持する MeganeGroup スキーマです。

このように定義した場合、スキーマ参照の際に type:array を指定することなくスキーマ配列を参照することができます。

(参照側)

まとめ:スキーマのプロパティの中に基本型・単一スキーマ・スキーマ配列を混在させる

説明が分かりにくいですね…。なんのことはない、今までの組み合わせです。

プロパティにおけるタイプの指定として、基本型データ(stringなど)を指定する方法、単一のスキーマを指定する方法、スキーマ配列を指定する方法をここまで学んできました。

では、それらを全て混在させる場合にはどのように書けばいいのでしょうか?

章立てするまでもないのですが、それぞれ順番に書くだけでおkです。この記事は筆者の備忘録を兼ねてるので、許してください…。

途中から名前がグダッてたけれども、ついに意味のない文字列になった。
ところで今回の学習は終了です。

 

Knowledgeカテゴリの最新記事