スキーマを構築する

スキーマエディターの活用

スキーマエディターは、API が利用するデータ構造の設計とモデリングを支援する強力なツールです。JSON Schema に基づいており、JSON または XML データ構造の設計に使用されます。

スキーマエディターを使用すると、次のことができます。

特定の API エンドポイントに合わせた API リクエストおよびレスポンスのボディを作成する。

1 つまたは複数の API で利用できるデータモデルを構築する。

すべてのスキーマはルートオブジェクトから始まります。スキーマを構築するには、このルートオブジェクトにプロパティを追加します。

スキーマの構築

プロパティを追加する

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

プロパティに名前を付ける

プロパティの名前（またはキー）を入力します。

プロパティタイプを選択する

一般的なデータ型を選択するか、事前定義済みスキーマへの参照を選択します。

詳細設定

Type Editor を使用して、各プロパティにデフォルト値や形式などのデータ型を割り当てます。

プロパティを管理する

プロパティを移動、コピー、削除して並べ替えます。また、説明を追加したり、必須としてマークしたりしてプロパティを補足できます。

代替方法

データベーステーブルまたは JSON schema ファイルからインポートして、新しいスキーマを作成することもできます。詳しくは JSON などからスキーマを生成をご覧ください。

プロパティタイプ

JSON Schema 標準に準拠して、Apidog Schema Editor は次の基本データ型をサポートしています。

型	説明
null	JSON の "null" 値を表します。
boolean	JSON の "true" または "false" 値に対応する、"true" または "false" 値を表します。
object	JSON の "object" 値に対応する、キーと値のペアの順序なしコレクションを表します。
array	JSON の "array" 値に対応する、値の順序付きリストを表します。
number	JSON の "number" 値に対応する、任意精度の 10 進数値を表します。
string	JSON の "string" 値に対応する、Unicode 文字の文字列を表します。

Array データ型

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

前述の標準データ構造に加えて、Apidog Schema Editor は次もサポートしています。

他のスキーマを参照: API ドキュメント内の別の場所で定義されたスキーマを参照し、再利用できます。

any: 任意のデータ型の値を表します。

スキーマ合成: 複数のスキーマを組み合わせて複雑なデータ構造を作成できます。

カスタマイズ: 特定の要件やデータモデリングのニーズに合わせて、ユーザーがスキーマをカスタマイズおよび調整できます。

他のスキーマの参照

「他のスキーマを参照」機能を使用して、以前に定義したスキーマを参照できます。

別のスキーマを参照すると、Schema Editor で参照先のスキーマを表示できます。

参照スキーマに関する重要なポイント:

元のスキーマに加えられた変更は、参照しているスキーマに反映されます。

参照スキーマは直接編集できません。変更するには、次の操作を行えます。

スキーマ名をクリックして元のスキーマに移動し、編集します。

スキーマで 参照解除 をクリックすると、スキーマは一連の独立したプロパティに変換され、個別に編集できるようになります。

特定のプロパティの定義だけを独立して変更する必要がある場合は、そのプロパティを 参照解除 できます。これにより個別に変更できます。元のスキーマへの変更は、参照解除されたプロパティには影響しません。

参照スキーマのすべてのプロパティがエンドポイントで必要ではない場合は、非表示 をクリックして不要なプロパティを隠すことができます。

スキーマ合成

データ構造内のプロパティが複数のデータ型を取り得る場合、スキーマ合成を使用して複数のスキーマを組み合わせることができます。

Apidog は次の合成キーワードをサポートしています。

キーワード	説明
allOf (AND)	プロパティが合成内で定義されたすべてのスキーマに準拠する必要があることを指定します。
anyOf (OR)	プロパティが合成内にリストされた任意のスキーマに準拠できることを指定します。
oneOf (XOR)	プロパティが合成内で定義されたスキーマのうち、1 つだけに準拠する必要があることを指定します。

スキーマ合成を選択すると、プロパティの下に「0」と「1」という名前のサブプロパティが表示され、合成内の各スキーマを表します。各サブプロパティのスキーマタイプを変更し、必要に応じて追加のスキーマを追加できます。

API ドキュメントでは、スキーマ合成は次のように表示されます。

OneOf の下に 2 つの任意オブジェクトが表示されていることが分かります。画像のようにそれらの名前を表示したい場合は、Type editor の title フィールドに名前を入力する必要があります。

カスタマイズ

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

プロパティ設定

各プロパティには、データ型の横にいくつかのボタンがあります。

ボタン	説明
*	プロパティが必須かどうかを示します。
N	プロパティが null 値を許可するかどうかを指定します。
Settings	Type Editor で詳細設定を編集できます。

Type Editor

Type Editor は、JSON Schema に準拠してプロパティを視覚的に説明します。

これらの詳細設定を構成すると、次の領域で有効になります。

レスポンス例を追加する際、設定に基づいて自動生成するようクリックできます。

API ドキュメントに表示されます。

リクエストボディで、設定に基づいて自動生成するようクリックできます。

リクエスト送信時、返されたデータは設定に照らして自動的に検証されます。

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

列挙型プロパティ

String、Integer、Number 型について、Apidog は enum をサポートしています。enum スイッチを切り替えることで、enum 値と説明を追加できます。また、enum 値の一括編集も実行できます。

モック

プロパティの詳細設定に加えて、モック値を入力することでフィールドのモック内容を指定できます。モック値は詳細設定内の設定よりも優先されます。

モック値は Faker.js 構文をサポートしており、ドロップダウンオプションから目的の faker データを直接選択できます。

モック値は固定値として入力することもできます。

XML 設定

XML データの場合、Apidog の Type Editor は追加の XML 設定を提供します。XML スイッチを有効にし、タグ名、名前空間などのプロパティを構成して、対応する XML 構造をプレビューできます。

HashMap、Dictionary、Array

HashMap は、Map、dictionary、または連想配列とも呼ばれます。これはキーと値のペアのコレクションであり、キー名は事前定義されたものではなく、任意の内容にできます。

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

ユーザー情報照会 API があり、返されるデータ形式に次の要件があるとします。

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

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

ユーザー ID がキーで、ユーザー情報が値である

Apidog でこれを定義するには:

新しいスキーマを作成し、「UserProfiles」という名前を付けます。

「UserProfiles」で、ルートノードを「object」型として指定します。次に Advanced Configuration をクリックし、additionalProperties を Allow に設定して、右側の Settings ボタンをクリックします。

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

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

保存をクリックすると、API ドキュメント内の戻りレスポンス例で、定義済みスキーマと例の値を確認できます。

additionalProperties を持つオブジェクト

実際の開発作業が反復されるにつれて、API から返されるオブジェクトには、元々定義されたオブジェクトと比較して additionalProperties が含まれる場合があります。OpenAPI 仕様によれば、この状況も "additionalProperties" 機能を使用して処理できます。

ユーザー情報照会 API があり、ユーザー ID でユーザー情報を照会する際に元々定義されていたレスポンスフィールドが name と email だったとします。現在、システムのアップグレードに伴い、他のフィールドも含めたいとします。

API ドキュメントを編集する際、次のように定義できます。データモデルのルートノードで Advanced Settings をクリックし、additionalProperties を Allow に設定し、フィールド値の型を any に設定します。

その後、API ドキュメントで定義済みのデータ構造と例の値を確認できます。

タプル

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

TIP

例を生成する際に複数の要素を生成したい場合は、ルートノードの詳細設定で要素の最小数と最大数を指定してください。

保存後、API ドキュメントで Generate Automatically をクリックすると、定義済みのデータ構造と例の値を確認できます。

ドキュメント内の戻りレスポンスでも、タプルの例の値を確認できます。

ツール

Apidog の Schema Editor は、非常に便利なツールをいくつか提供しています。

ツール	説明
Generate from JSON etc.	このツールを使用すると、JSON、XML データ、その他のソース、またはデータベーステーブル構造から直接スキーマを自動生成できます。詳しくは JSON などからスキーマを生成をご覧ください。
Preview	このツールはスキーマ定義に準拠したモックデータを作成し、想定されるデータのプレビューを提供します。
Generate code	このツールは、さまざまなプログラミング言語でデータ構造定義コードを生成できます。詳しくはコードを生成をご覧ください。
JSON Schema	このツールを使用すると、微調整やカスタマイズのために JSON スキーマを直接編集できます。

FAQ

Q: 文字列プロパティに複数の列挙値があり、さまざまな場所で使用される場合、この enum を全体で一貫して参照するにはどうすればよいですか？

A: このプロパティを単一のプロパティで構成される独立したスキーマとして定義することで、API ドキュメントの異なる部分で一貫して参照できるようになります。

スキーマを構築する

スキーマエディターの活用#

スキーマの構築#

プロパティタイプ#

他のスキーマの参照#

スキーマ合成#

カスタマイズ#

プロパティ設定#

Type Editor#

列挙型プロパティ#

モック#

XML 設定#

HashMap、Dictionary、Array#

additionalProperties を持つオブジェクト#

タプル#

ツール#

FAQ#

スキーマエディターの活用

スキーマの構築

プロパティタイプ

他のスキーマの参照

スキーマ合成

カスタマイズ

プロパティ設定

Type Editor

列挙型プロパティ

モック

XML 設定

HashMap、Dictionary、Array

additionalProperties を持つオブジェクト

タプル

ツール

FAQ