Apidog Docs
🇯🇵 日本語
  • 🇺🇸 English
  • 🇯🇵 日本語
HomeLearning CenterSupport CenterAPI References
HomeLearning CenterSupport CenterAPI References
Discord Community
Slack Community
X / Twitter
🇯🇵 日本語
  • 🇺🇸 English
  • 🇯🇵 日本語
  1. Schemas
  • Apidog学習センター
  • はじめに
    • Apidog紹介
    • Apidog基本操作
      • 概要
      • 新しい APIを作成
      • APIにリクエストを送信
      • アサーションを追加
      • テストシナリオを作成
      • APIドキュメントを共有
      • さらなる探究
      • リクエストを送信してAPIとして保存
    • Apidog基本知識
      • Apidog操作方法
      • Apidogの基本概念
    • 移行
      • 概要
      • 手動インポート
      • 定期インポート
      • インポートオプション
      • データのエクスポート
      • Import from...
        • Postman からインポート
        • OpenAPI(Swagger)仕様のインポート
        • cURLのインポート
        • Markdownのインポート
        • Insomniaからのインポート
        • apiDocからのインポート
        • .harファイルのインポート
        • WSDLのインポート
  • API設計
    • 概要
    • コンポーネント
    • 常用フィールド
    • グローバルパラメータ
    • API変更履歴
    • プロジェクトの作成
    • 一括API管理
    • APIの基本
    • 複数のリクエストボディ例の設定
    • Schemas
      • 概要
      • 新規Schemaの作成
      • スキーマを構築する
      • JSONなどからのSchema生成
    • Security schemes
      • 概要
      • Security Schemeの作成
      • Security Schemeの使用
      • オンラインドキュメントにおけるSecurity Scheme
    • 高度な機能
      • APIをテストステップとしてインポート
      • パラメータリストの表示形式
      • APIのカスタムフィールド
      • APIのステータス
      • API固有識別子
  • API開発とデバッグ
    • 概要
    • リクエストの生成
    • リクエストの送信
    • コード生成機能
    • APIケース
    • 動的な値
    • レスポンスの検証
    • 設計優先 & リクエスト優先
    • 環境 & 変数
      • 概要
      • 環境とサービス
      • 変数の使い方
    • Vault secrets
      • 概要
      • AWS Secrets Manager
      • Azure Key Vault
      • HashiCorp Vault
    • 前/後処理
      • 概要
      • Wait
      • 変数の抽出
      • アサーション
      • データベース操作
        • 概要
        • MongoDB
        • Redis
        • Oracle クライアント
      • スクリプト利用
        • 概要
        • 前処理スクリプト
        • 後処理スクリプト
        • Postmanスクリプトリファレンス
        • 共通スクリプト
        • 他のプログラミング言語の呼び出し
        • JSライブラリの使用
        • レスポンスの可視化
        • スクリプトの例
          • その他の例
          • スクリプトを使用したリクエストメッセージの変更
          • スクリプトでの変数の使用
          • アサーションスクリプト
    • 動的値モジュール
  • APIモック
    • 概要
    • スマートMock
    • カスタムMock
    • Mockの優先順位
    • Mockスクリプト
    • クラウドMock
    • セルフホストランナーMock
    • Mock言語 (ロケール)
  • 自動テスト
    • 概要
    • テストレポート
    • テストシナリオ
      • テストシナリオの作成
      • 他のプロジェクトからAPI/APIケースをインポートする
      • リクエスト間でデータを渡す
      • API/APIケースからのデータ同期
      • フロー制御条件
      • テストシナリオのエクスポート
    • テストシナリオ実行
      • データ駆動型テスト
      • スケジュールタスク
      • テストシナリオを一括実行する
      • 他のプロジェクトのAPIの実行環境を管理する
      • テストシナリオを実行する
    • APIテスト
      • 統合テスト
      • 回帰テスト
      • エンドツーエンド(E2E)テスト
      • パフォーマンステスト
    • Apidog CLI
      • 概要
      • Apidog CLIのインストールと実行
      • Apidog CLI オプション
    • CI/CD
      • 概要
      • Jenkinsとの連携
      • Gitlabとの統合
  • APIドキュメント公開
    • 概要
    • Google AnalyticsとDoc Sitesの連携
    • CORS プロキシ
    • クイック共有
    • 可視性設定
    • ドキュメントURLに値を埋め込む
    • APIドキュメントを表示する
    • フォルダツリー設定
    • API SEO設定
    • カスタムレイアウト
    • ドキュメント検索
    • カスタムドメイン
    • ドキュメントサイトの公開
    • APIバージョン
      • 概要
      • APIバージョンの作成
      • APIバージョンの公開
      • APIバージョンごとにAPIの共有
  • リクエスト送信
    • 概要
    • GraphQL
    • gRPC
    • WebSocket
    • SSEデバッグ
    • SOAP/Webサービス
    • デバッグ用のリクエストプロキシエージェントを使用する
    • Socket.IO
    • リクエスト作成
      • リクエストの基本
      • パラメータとボディ
      • リクエストヘッダー
      • リクエスト設定
      • HTTP/2
      • リクエスト履歴
    • 認証と認可
      • 概要
      • CAとクライアント証明書
      • Apidogがサポートする認可タイプ
      • Digest Auth
      • OAuth 1.0
      • OAuth 2.0
      • Hawk Authentication
      • Kerberos
      • NTLM
      • Akamai EdgeGrid
    • レスポンスとクッキー
      • 概要
      • ApidogのAPIレスポンス
      • Cookieの作成と送信
      • リクエストのデバッグ
      • リクエストをAPIとして保存
  • ブランチ管理
    • 概要
    • 新しいスプリントブランチの作成
    • スプリントブランチの管理
    • ブランチ内でのAPIテスト
    • ブランチでAPIの設計
    • スプリントブランチのマージ
  • Apidog MCP Server
    • 概要
    • Apidogプロジェクト内のAPI仕様をApidog MCPサーバー経由でAIに接続する
    • Apidogが公開したオンラインAPIドキュメントをApidog MCPサーバー経由でAIに接続する
    • Apidog MCPサーバーを介してOpenAPIファイルをAIに接続する
  • ベストプラクティス
    • ガイド:ChatGPT APIのトークンとコスト計算
    • Apidog コラボレーションワークフロー
    • API署名の取り扱い方法
    • Apidogでの認証状態の管理
    • OAuth 2.0で保護されたAPIにアクセスする方法
  • 管理
    • オンボーディングチェックリスト
      • 基本概念
      • Apidogスタートアップガイド
    • チーム管理
      • チーム管理
      • チームメンバーの管理
      • メンバーの役割と権限設定
      • チーム活動
      • チームリソース
        • 一般ランナー
        • チーム変数
        • リクエストプロキシエージェント
        • データベース接続
      • リアルタイムコラボレーション
        • チームコラボレーション
    • プロジェクト管理
      • プロジェクト管理
      • プロジェクトメンバーの管理
      • 通知設定
    • 組織管理
      • シングルサインオン(SSO)
        • 概要
        • Microsoft Entra IDの設定
        • Okta設定
        • 組織のSSOを設定する
        • チームへのグループのマッピング
        • ユーザーアカウントの管理
      • SCIMプロビジョニング
        • SCIMプロビジョニング入門
        • Microsoft Entra ID
        • Okta
      • 組織リソース
        • セルフホストランナー
  • 請求情報
    • 概要
    • プランのアップグレード
    • クレジット
    • クレジットカードが使えない?
    • サブスクリプションの管理
  • アドオン
    • API Hub
    • Apidog IntelliJ IDEA プラグイン
    • リクエストプロキシ
      • Apidogウェブでのリクエストプロキシ
      • 共有ドキュメントでのリクエストプロキシ
      • Apidogクライアントでのリクエストプロキシ
    • ブラウザ拡張機能
      • Microsoft Edge
      • Chrome
  • アカウント & 設定
    • アカウント設定
    • 言語設定
    • データバックアップ
    • ネットワークプロキシ設定
    • ホットキー
    • Apidogの更新
    • OpenAPIアクセストークンの生成
    • アカウント削除
  • 参考資料
    • Swagger拡張機能
    • Socket通信:パケットの分断と結合
    • 用語の説明
    • よくある質問
    • API-デザインファーストアプローチ
    • Apidog OpenAPI/Swagger仕様拡張
    • JSONPath
    • XPath
    • 正規表現
    • JSONスキーマ
    • CSVファイルフォーマット
    • Java環境のインストール
    • ランナーのデプロイ環境
    • ApidogフレーバーMarkdown
  1. Schemas

スキーマを構築する

Schema Editorの使い方#

Schema Editorは、APIで使用するデータ構造を設計・モデリングするための強力なツールだ。JSON Schemaをベースにしており、JSON や XML のデータ構造を設計するのに使う。
Schema Editorでできること:
APIのリクエストとレスポンスのボディを設計できる
複数のAPIで使える共通のデータモデルを作れる
スキーマはすべてルートオブジェクトから始まる。スキーマを作るには、このルートオブジェクトにプロパティを追加していく。
スキーマの作り方:
1
プロパティの追加
ルートオブジェクトの横にある + (子ノードを追加)をクリックして、新しいプロパティを追加する
2
プロパティ名の設定
プロパティの名前(キー)を入力する
3
プロパティタイプの選択
一般的なデータ型を選ぶか、既存のスキーマを参照する
4
詳細設定
Type Editorで各プロパティのデフォルト値やフォーマットなどのデータ型を設定する
5
プロパティの管理
プロパティの移動、コピー、削除ができる。説明を追加したり、必須項目として設定したりもできる
データベースのテーブルや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を編集できる。

プロパティの設定#

各プロパティには、データ型の横に以下のボタンがある:
image.png
*:プロパティが必須かどうかを示す
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で、返されるデータ形式が以下の要件を持つ場合:
1.
返されるデータはオブジェクト
2.
オブジェクトの子要素はHashMapのキーと値のペア
3.
ユーザー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ドキュメントの異なる箇所で一貫して参照できる。
Previous
新規Schemaの作成
Next
JSONなどからのSchema生成
Built with