データモデルを構築する

データモデルエディターの使い方

データモデルエディターは、APIで使用するデータ構造を設計・モデリングするための強力なツールだ。JSON Schemaをベースにしており、JSON や XML のデータ構造を設計するのに使う。

データモデルエディターでできること：

APIのリクエストとレスポンスのボディを設計できる

複数のAPIで使える共通のデータモデルを作れる

データモデルはすべてルートオブジェクトから始まる。データモデルを作るには、このルートオブジェクトにプロパティを追加していく。

データモデルの作り方：

プロパティの追加

ルートオブジェクトの横にある ＋ （子ノードを追加）をクリックして、新しいプロパティを追加する

プロパティ名の設定

プロパティの名前（キー）を入力する

プロパティタイプの選択

一般的なデータ型を選ぶか、既存のデータモデルを参照する

詳細設定

タイプエディターで各プロパティのデフォルト値やフォーマットなどのデータ型を設定する

プロパティの管理

プロパティの移動、コピー、削除ができる。説明を追加したり、必須項目として設定したりもできる

データベースのテーブルやJSON Schemaファイルからインポートして新しいデータモデルを作ることもできる。詳しくはJSONなどからデータモデルを生成するを参照。

プロパティタイプ

JSON Schema標準に準拠して、Apidogデータモデルエディターは以下の基本データ型をサポートしている：

null：JSONの「null」値を表す

boolean：「true」または「false」の値を表す。JSONの「true」「false」に対応

object：キーと値のペアの順序なしコレクション。JSONの「object」に対応

array：順序付きの値のリスト。JSONの「array」に対応

array型を使うと、自動的に ITEMS というサブレベルのプロパティが生成される。これは配列内の要素のデータ型を指定するものだ。

number: 任意精度の10進数値。JSONの「number」に対応

string: Unicodeの文字列。JSONの「string」に対応

上記の標準的なデータ構造に加えて、Apidogデータモデルエディターは以下もサポートしている：

他のデータモデルの参照：APIドキュメント内の他の場所で定義されたデータモデルを参照・再利用できる

any：どのデータ型でも受け入れ可能な値を表す

データモデルの組み合わせ：複数のデータモデルを組み合わせて複雑なデータ構造を作れる

カスタマイズ：特定の要件やデータモデリングのニーズに合わせてデータモデルをカスタマイズできる

他のデータモデルの参照

「他のデータモデルを参照」機能を使って、既に定義済みのデータモデルを参照できる。

参照後、データモデルエディターで参照したデータモデルを確認できる。

元のデータモデルを変更すると、参照しているデータモデルにも反映される

参照したデータモデルは直接編集できないが、以下の方法で変更可能：

データモデル名をクリックして元のデータモデルに移動して編集

データモデルの 参照解除 をクリックすると、個別に編集可能な独立したプロパティに変換される

特定のプロパティの定義だけを独立して修正したい場合は、そのプロパティを 参照解除 できる。元のデータモデルの変更は参照解除したプロパティには影響しない

APIで参照データモデルのすべてのプロパティが必要ない場合は、非表示 をクリックして不要なプロパティを隠せる

データモデルの組み合わせ

データ構造のプロパティが複数の異なるデータ型を持つ可能性がある場合、データモデルの組み合わせを使用できる。

Apidogは以下の組み合わせキーワードをサポートしている：

allOf(AND)：プロパティが定義されたすべてのデータモデルに従う必要がある

anyOf(OR)：プロパティが定義されたデータモデルのいずれかに従えばよい

oneOf(XOR)：プロパティが定義されたデータモデルの1つだけに従う必要がある
データモデル組み合わせを選択すると、「0」と「1」という名前のサブプロパティが表示される。これらは組み合わせ内の各データモデルを表す。各サブプロパティのデータモデルタイプを変更したり、追加のデータモデルを追加したりできる。

APIドキュメントでは、データモデルの組み合わせは次のように表示される：

OneOfの下に2つのオプションオブジェクトが表示されているのに気付くだろう。画像のように名前を表示したい場合は、タイプエディターのtitleフィールドにそれぞれの名前を入力する必要がある。

カスタマイズ

「カスタマイズ」を選択すると、エディタで直接JSON Schemaを編集できる。

プロパティの設定

各プロパティには、データ型の横に以下のボタンがある：

*：プロパティが必須かどうかを示す

N：プロパティがnull値を許容するかどうかを指定

設定：タイプエディターで詳細設定を編集できる

タイプエディター

タイプエディターは、JSON Schemaに準拠してプロパティを視覚的に表現する。

詳細設定は以下の場面で活用される：

レスポンス例を追加する際、設定に基づいて自動生成できる

APIドキュメントに表示される

リクエストボディで設定に基づいて自動生成できる

リクエスト送信時、返されたデータが設定に基づいて自動的に検証される

モックサービスで、設定に基づいてレスポンスデータが生成される

列挙型プロパティ

String、Integer、Number型では、列挙型（enum）がサポートされている。enumスイッチをオンにすると、enum値とその説明を追加できる。さらに、enum値の一括編集も可能だ。

Mock

プロパティの詳細設定に加えて、モック値を指定してフィールドのモックコンテンツを設定できる。モック値は詳細設定よりも優先される。

モック値はFaker.js の構文をサポートしており、ドロップダウンから直接必要なfakerデータを選択できる

モック値は固定値としても入力可能

XML設定

XML形式のデータについて、Apidogのタイプエディターには追加のXML設定がある。XML スイッチを有効にして、タグ名やネームスペースなどのプロパティを設定し、対応するXML構造をプレビューできる。

HashMap、Dictionary、配列

HashMapは、Mapやdictionary、連想配列とも呼ばれる。キーと値のペアのコレクションで、キー名は事前に定義されたものではなく、任意の内容が可能だ。

OpenAPI仕様では、文字列キーを持つHashMapの定義をサポートしている。これは要素タイプをobjectに設定し、additionalPropertiesキーワードを使用してキーと値のペアの値の型を指定することで実現する。

例えば、ユーザー情報を照会するAPIで、返されるデータ形式が以下の要件を持つ場合：

返されるデータはオブジェクト

オブジェクトの子要素はHashMapのキーと値のペア

ユーザーIDがキー、ユーザー情報が値

ApidogでAPIドキュメントを編集する際は、次のように定義できる：

新しいデータモデルを作成し、「UserProfiles」と名付ける

「UserProfiles」で、ルートノードを「object」型に指定。「詳細設定」をクリックし、「additionalProperties」を「許可」に設定し、右側の「設定」ボタンをクリック

ポップアップで必要なユーザー情報を追加。ユーザーの名前とメールアドレスをオブジェクトのフィールドとして設定。自動保存される

APIドキュメントのレスポンスで、ルートノードにデータモデルを参照し、作成した「user profiles」を選択

保存すると、APIドキュメント内の戻り値レスポンス例で定義したデータモデルとサンプル値が確認できる

additionalPropertiesを持つオブジェクト

実際の開発が進むにつれて、APIが返すオブジェクトが当初定義したものよりも追加のプロパティを持つことがある。OpenAPI仕様では、この状況も「additionalProperties」機能で対応できる。

例えば、ユーザーIDでユーザー情報を照会するAPIで、当初は name と email のみが定義されていたレスポンスフィールドに、システムのアップグレードで他のフィールドも含めたい場合：

APIドキュメントの編集時、次のように定義できる：データモデルのルートノードで「詳細設定」をクリックし、「additionalProperties」を「許可」に設定し、フィールド値の型を「any」に設定する。

すると、APIドキュメントで定義したデータ構造とサンプル値が確認できる。

Tuples

通常、配列の内部要素は同じ型である必要があるが、タプルは異なる型のデータを含むことができる。(0,"A",2,"C")のような、文字列と整数型の両方を含むタプルを定義したい場合、データモデルで要素型を array に設定し、items の型を組み合わせパターンの anyOf に設定し、string 型とinteger 型の子要素をそれぞれ追加する。

サンプル生成時に複数の要素を生成したい場合は、ルートノードの詳細設定で要素の最小数と最大数を指定する。

保存後、APIドキュメントの「自動生成」をクリックすると、定義したデータ構造とサンプル値が確認できる。

ドキュメントのレスポンス例でもタプルのサンプル値を確認できる。

ツール

Apidog のデータモデルエディターには、以下の便利なツールが用意されている:

JSONなどから生成: JSON、XMLデータなどから、またはデータベースのテーブル構造から直接データモデルを自動生成できる。詳しくはJSONなどからデータモデルを生成するを参照

プレビュー: データモデル定義に従ったモックデータを生成し、期待されるデータをプレビューできる

コード生成: 様々なプログラミング言語でのデータ構造定義コードを生成できる。詳しくはコード生成を参照

JSON Schema: JSON Schemaを直接編集して、細かい調整やカスタマイズができる

FAQ

Q: 文字列プロパティが複数の列挙値を持ち、様々な場所で使用される場合、このenumを一貫して参照するにはどうすればいい？

A: このプロパティを単一のプロパティで構成される独立したデータモデルとして定義すれば、APIドキュメントの異なる箇所で一貫して参照できる。

データモデルを構築する

データモデルエディターの使い方#

プロパティタイプ#

他のデータモデルの参照#

データモデルの組み合わせ#

カスタマイズ#

プロパティの設定#

タイプエディター#

列挙型プロパティ#

Mock#

XML設定#

HashMap、Dictionary、配列#

additionalPropertiesを持つオブジェクト#

Tuples#

ツール#

FAQ#

データモデルエディターの使い方

プロパティタイプ

他のデータモデルの参照

データモデルの組み合わせ

カスタマイズ

プロパティの設定

タイプエディター

列挙型プロパティ

Mock

XML設定

HashMap、Dictionary、配列

additionalPropertiesを持つオブジェクト

Tuples

ツール

FAQ