スキーマを構築する

Schema Editorの使い方

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

Schema Editorでできること：

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

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

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

スキーマの作り方：

プロパティの追加

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

プロパティ名の設定

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

プロパティタイプの選択

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

詳細設定

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

プロパティの管理

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

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

プロパティタイプ

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

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 Schema Editorは以下もサポートしている：

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

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

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

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

他のスキーマの参照

「他のスキーマを参照」機能を使って、既に定義済みのスキーマを参照できる。

参照後、Schema Editorで参照したスキーマを確認できる。

元のスキーマを変更すると、参照しているスキーマにも反映される

参照したスキーマは直接編集できないが、以下の方法で変更可能：

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

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

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

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

スキーマの組み合わせ

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

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

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

anyOf(OR)：プロパティが定義されたスキーマのいずれかに従えばよい

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

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

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

カスタマイズ

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

プロパティの設定

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

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

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

設定：Type Editorで詳細設定を編集できる

タイプエディター

タイプエディターは、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ドキュメントの異なる箇所で一貫して参照できる。

スキーマを構築する

Schema Editorの使い方#

プロパティタイプ#

他のスキーマの参照#

スキーマの組み合わせ#

カスタマイズ#

プロパティの設定#

タイプエディター#

列挙型プロパティ#

Mock#

XML設定#

HashMap、Dictionary、配列#

additionalPropertiesを持つオブジェクト#

Tuples#

ツール#

FAQ#

Schema Editorの使い方

プロパティタイプ

他のスキーマの参照

スキーマの組み合わせ

カスタマイズ

プロパティの設定

タイプエディター

列挙型プロパティ

Mock

XML設定

HashMap、Dictionary、配列

additionalPropertiesを持つオブジェクト

Tuples

ツール

FAQ