OpenAPI ビルダーでのビジュアル・エディターの使用

キャンバスのスクロール

キャンバスには、OpenAPIの仕様がブロックベースで表示されている。 各エンドポイントには HTTPとパスを持つブロックがあり、パラメータとレスポンス用のネストされたブロックがあります。 ブロックについて詳しくは、 ブロックを参照してください。

パレットを開く

パレットには、 OpenAPI 仕様に追加できるすべてのブロックが、API エンドポイント、タイプ、値、参照、コネクターなどのカテゴリーにグループ化されて表示されます。

テキスト・ビューを開く

キャンバス上のブロック・ベースのビューは、 OpenAPI 仕様のテキスト・ベースの JSON ビューに対応しています。 開始ブロックのテキスト・ビューには OpenAPI 仕様全体が表示され、その他のブロックのテキスト・ビューにはそのブロックの仕様の抜粋のみが表示されます。

• 鉛筆アイコンをクリックして、ブロックのテキスト・ビューを開きます。 再クリックしてテキスト・ビューを閉じます。

ブロック構成のフライアウトを開く

構成を開くには、以下のようにします。

• ブロックの歯車アイコンをクリックします。 アイコンを再クリックして、構成の吹き出しを閉じます。

最上位ブロックの作成

トップレベル・エディターにはトップレベル・パレットがあります。 構成内にブロックを作成するには、以下のようにします。

• パレットからドラッグして、最上位のキャンバスにドロップします。

構成フライアウトでのブロックの作成

構成フライアウトには、独自のパレットが組み込まれています。 構成内にブロックを作成するには、以下のようにします。

• フライアウトのパレットからドラッグし、フライアウトのキャンバスにドロップします。

ブロックの更新

ブロックを更新するには

• そのテキスト・フィールドの 1 つを選択してから、新しい値を入力します。

ブロックの削除

ブロックを削除するには、以下のいずれかの方法を使用します。

• ブロックを選択してから、キーボードの Delete キーを押します。
• ブロックを右クリックし、メニューから 「削除」 を選択します。

編集の削除

以下のいずれかの方法で、編集を元に戻すことができます (AI 提案からの自動編集でも手動編集でも)。

• キーボード・ショートカット Ctrl-z を押します。
• 背景を右クリックし、メニューから 「元に戻す」 を選択します。

JSON テキストの更新

テキスト JSON ビューからブロックを作成、更新、または削除できます。

• 更新を行い、 「変更の適用」をクリックします。

「変更の適用」 ボタンは、JSON がエラー・フリーの場合にのみ有効になります。 エラーが発生した場合は、エラーを解決して変更を適用するか、編集アイコンをクリックしてテキストの変更を破棄し、テキストフライアウトを閉じることができます。

エンドポイント・ブロック

エンドポイント・ブロックは、操作メソッドとパスを構成することによって API 操作を指定します。 上部にノッチ、下部にバンプを付けた形をしている。 エンドポイント・ブロックは、開始ブロックまたは別のエンドポイント・ブロックの下部にスナップすることができます。

エンドポイント・ブロックには、パラメーター、応答、および (特定のメソッドの場合) 要求本体のタイプ・ブロックをスナップするための C 字型の穴があります。 パラメータとして使用されるタイプブロックは、位置、名前、および「required?」を取得します フラグ。 レスポンスとして使用されるタイプブロックは、 HTTP ステータスコードを取得します。 エンドポイントは、複数のパラメーターまたは応答を持つことができますが、最大で 1 つの要求本体を持つことができます。

タイプ・ブロック

タイプ・ブロックは JSON スキーマを指定します。 上部にはノッチを配置し、複数のスキーマが予期されるコンテキストで使用する場合は下部にバンプを配置します。 タイプ・ブロックは、エンドポイント・ブロック、配列タイプ・ブロック、オブジェクト・タイプ・ブロック、および特定のコネクター・ブロックの C 字型のホールにスナップすることができます。 タイプ・ブロックは、定義ブロックの下部にスナップすることもできます。

• 列挙型のタイプ。 値の固定セットがリストされます。 例: ["red", "green", "blue"]。 列挙型ブロックには右側にメスのジグソー・コネクターがあり、そこで値ブロックをスナップすることができます。 値の数を変更するには、「+」/「-」を使用します。

以下の JSON スクリプトは、 enum タイプの例を示しています。

{
  "Color": {
    "type": "string",
    "enum": [
      "Red",
      "Green",
      "Blue"
    ]
  }
}

• テキストのストリングのタイプ。 例: Hello world!。

以下の JSON スクリプトは、 string タイプの例を示しています。

{
  "node_id": {
    "type": "string",
    "example": "MDEyOk9yZ2FuaXphdGlvbjE=",
    "x-ibm-grounded-description": false
  }
}

• 整数のタイプ。 整数 (例: 3、 42、 0、 -2048)。

以下の JSON スクリプトは、 Integer タイプの例を示しています。

{
  "id": {
    "type": "integer",
    "example": 1,
    "x-ibm-grounded-description": false
  }
}

• 数値を入力します。 浮動小数点または整数 (例: 3、 2.99、 0、 -123.456)。

以下の JSON スクリプトは、 Number タイプの例を示しています。

{
  "Value": {
    "type": "number",
    "example": 1.5,
    "x-ibm-grounded-description": false
  }
}

• boolean の値を入力します。 例: true または false。

以下の JSON スクリプトは、 Boolean タイプの例を示しています。

{
  "site_admin": {
    "type": "boolean",
    "x-ibm-grounded-description": false
  }
}

• 項目の配列のタイプ。 例: [1,2,3]。 「type: array」ブロック自体は C 字型であるため、許可される項目のタイプを指定するために別のタイプ・ブロックをスナップインすることができます。

以下の JSON スクリプトは、 Array タイプの例を示しています。

{
  "events": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "example": [
      "deployment"
    ],
    "x-ibm-grounded-description": false
  }
}

• オブジェクトのタイプ。ストリング・キーから JSON 値へのマッピングです。 「type: object」ブロック自体は C 字型であるため、他のタイプのブロックをプロパティー用にスナップすることができます。 プロパティーとして「type: object」にネストされたタイプ・ブロックは、キー (通常は「Name」) と「required?」を取得します。 フラグ。

以下の JSON スクリプトは、 Object タイプの例を示しています。

{
  "permissions": {
    "type": "object",
    "example": {
      "deployments": "write",
      "metadata": "read",
      "pull_requests": "read",
      "statuses": "read"
    }
  }
}

• NULL タイプでは、NULL 値のみが許可されます。

以下の JSON スクリプトは、 Null タイプの例を示しています。

{
  "type": [
    "string",
    "null"
  ],
  "maxLength": 255
}

値ブロック

値ブロックは JSON 値を指定します。 左側に男性用ジグソー・コネクターが付いた形をしています。 値ブロックをメスのジグソー・コネクターにスナップして、他のブロックの構成でデフォルト値またはサンプル値を指定することができます。 値ブロックは、配列値ブロック、オブジェクト値ブロック、または列挙ブロックの女性用ジグソー・コネクターにスナップすることもできます。

• テキストのストリング。 例: Hello, world!。

• 整数。 例: 3、 42、 0、 -2048。

• 浮動小数点数または整数です。 例: 3、 2.99、 0、 -123.456。

• この値は、チェック・ボックスが選択されている場合は true、それ以外の場合は false です。 例: true。

• 値の配列 (配列型のインスタンス) です。 配列バリュー・ブロック自体には右側にメスのジグソー・コネクターがあるため、他のバリュー・ブロックを項目用にスナップすることができます。 項目数を変更するには、「+」/「-」を使用します。

• ストリング・キーから値へのマッピング (オブジェクト・タイプのインスタンス)。 オブジェクト・バリュー・ブロック自体には右側にメスのジグソー・コネクターがあるため、プロパティーのために他の値ブロックをスナップすることができます。 プロパティーとしてオブジェクト値にネストされた値ブロックは、ストリング・キー (「Name」) を取得します。 プロパティーの数を変更するには、「+」/「-」を使用します。

• ヌル値 (ヌル・タイプのインスタンス)。

参照ブロック

参照ブロックは、エディターがタブに表示するスキーマ定義を参照します。 上部にはノッチを配置し、複数のスキーマが予期されるコンテキストで使用する場合は下部にバンプを配置します。 参照ブロックは、それが参照する定義が予期される場所であればどこでも使用することができます。 言い換えると、タイプ・ブロックを指す参照は、任意のプレース・タイプ・ブロックにスナップすることができます。 参照ブロックには、参照されているスキーマ定義の場所を識別する URI を持つストリングが含まれています。

コネクター・ブロック

コネクター・ブロックは、新しいタイプ・ブロックのように機能するスキーマに他のブロックを構成します。 上部にはノッチを配置し、複数のスキーマが予期されるコンテキストで使用する場合は下部にバンプを配置します。 コネクター・ブロックは、タイプ・ブロックを使用できる場所であればどこでも使用できます。

• anyOf,に対してバリデーションを行うには、少なくとも1つのスキーマに対してデータが有効でなければなりません。 これは、一部のプログラミング言語では共用体タイプに似ています。 anyOf ブロック自体は C 字型であるため、代替のために他のスキーマをスナップすることができます。

• allOf,に対してバリデーションを行うには、データはすべてのスキーマに対して有効でなければなりません。 これは、一部のプログラミング言語では交点タイプに似ています。 allOf ブロック自体は C 字型であるため、他のスキーマを結合のためにスナップすることができます。

• oneOf,に対してバリデーションを行うには、データがちょうど1つのスキーマに対して有効でなければなりません。 oneOf ブロック自体は C 字型であるため、代替のために他のスキーマをスナップすることができます。

• 検証するしないに関わらず、データはスキーマに対して無効でなければなりません。 ブロック自体はC字型なので、別の図形をはめ込むことができます。

• 空のスキーマ（{}）は、有効なJSON値をすべて受け入れます。 これは、一部のプログラミング言語における「Any」タイプに似ています。 真のブール値と混同しないこと。真のブール値はスキーマではない。 否定された空のスキーマ（{"not":{}}）は、値を一切受け付けません。 偽のブール値と混同しないように。これはスキーマではない。

• if, then, else ブロックを使用すると、別のスキーマの結果に基づいてコンポーネント・スキーマを適用できます。 条件、then 節、else 節の C 字型の穴があり、それぞれが他のスキーマ・ブロックを 1 つしか保持できません。