コードエディタでの API 仕様の作成

API Designer のコードエディタを使用して、API 仕様を直接 RAML 0.8、RAML 1.0、または OAS 2.0 (JSON または YAML) で作成できます。

始める前に

Anypoint Platform で、自分のユーザ ID に Design Center Developer 権限を割り当てておく必要があります。

手順

  1. 作業できる API 仕様プロジェクトを作成します。

    1. Design Center の [Projects (プロジェクト)] ページで、​[Create (作成)] をクリックして [Create API Specification (API 仕様を作成)] をクリックします。

    2. 開いたダイアログボックスの [New Specification (新しい仕様)] セクションでプロジェクトに名前を付けて、オプション [Code editor (コードエディタ)] を選択してコードエディタを使用します。

    3. プロジェクトで作成するスタブ仕様ファイルを RAML と OAS のどちらの形式にするかを選択します。デフォルトでは RAML 1.0 ファイルを作成しますが、プロジェクトの作成後に RAML 0.8 や OAS に変更することができます。実際に、API 仕様を作成するプロジェクトでは、RAML ファイルと OAS ファイルを混在させることができます。

    結果: コードエディタが開きます。エディタは 3 つのパネルに分かれています。

    • 左側のパネルには、プロジェクトファイルのリストが表示されています。スタブ仕様ファイルも表示されています。ファイル名の右側にある 3 つのドットを右クリックして [Rename (名前の変更)] を選択すると、このファイルの名前と拡張子を変更できます。

      1 つのプロジェクトで複数の API 仕様や関連ファイルを作成できます。[Files (ファイル)] パネルでプラス記号をクリックして新しいファイルを作成するか、またはプラス記号の横にあるドットをクリックしてファイルをインポートします。

    • 中央パネルには、API 仕様を作成するためのエディタがあります。プロジェクトの作成時や新しい API 仕様の開始時には、プロジェクト作成時の選択に応じて、RAML または OAS 形式の仕様ファイルの最初の 2 行が表示されています。RAML から OAS、またはその逆に切り替えたい場合は、これらの行 (およびファイル名拡張子) を変更できます。

    • 右側のパネルには、中央パネルに表示されている API 仕様に含まれる型やリソースのリストが表示されます。

  2. API 仕様を作成します。

    エディタでの作業中には、多くのコマンドを使用して仕様内を移動したり、仕様の内容を操作したりできます。F1 キーを押すと、いつでもこれらのリストが表示されます。このリストには、大半のコマンドのキーボードショートカットも表示されます。

    以下のタスクも実行できます。

    プロジェクトへのファイルと API フラグメントのインポート

    ファイルを 1 つずつ、または .zip ファイルにまとめてインポートできます。RAML 1.0 ファイル、JSON ファイル、または OpenAPI Specification (OAS) 2.0 ファイル (JSON または YAML) がサポートされています。コンピュータ上のローカルファイルを指定するか、またはファイルがオンラインで保存されている場合は URL を指定できます。

    ファイルのインポートについての詳細とインポート手順は、このトピックの最後にある​「関連情報」​にリンクがある「API プロジェクトへのファイルのインポート」を参照してください。

    プロジェクトへの API フラグメントの追加についての詳細は、このトピックの最後にある​「関連情報」​にリンクがある「API 仕様プロジェクトへの連動関係としての RAML API フラグメントの追加」を参照してください。

    API コールのシミュレーション

    API 仕様の作成中であっても、以下を指定したエンドポイントへのコールをシミュレートすることができます。

    • API が成功時に返す HTTP ステータスコード

    • 実際の実装が返すデータの例

      詳細については、このトピックの最後にある​「関連情報」​にリンクがある「API コールのシミュレーション」を参照してください。

    API プロジェクトまたは仕様のエクスポート

    プロジェクトはいつでも .zip ファイルとしてエクスポートできます。左側のペインの [Files (ファイル)] 見出しの横にあるドットをクリックして、​[Export (エクスポート)] を選択します。

    ファイルのダウンロード

    ファイル名の右側にあるドットをクリックして [Download (ダウンロード)]​を選択します。

    別の形式でのファイルのダウンロード

    仕様のファイル名の右側にあるドットをクリックして [Download as (名前を付けてダウンロード)] を選択します。仕様は、サポートされている他の形式のいずれかでダウンロードできます。仕様が RAML 形式であれば、OAS YAML または OAS JSON 形式でダウンロードできます。仕様が OAS 形式であれば、RAML 0.8 または RAML 1.0 形式でダウンロードできます。

    このオプションを使用してダウンロードしたファイルが有効である保証はありません。このオプションの目的は、新しい仕様の開発の基礎を提供すること、または新しい形式で元の仕様の開発を継続できるようにすることです。

次にすること

仕様が完成したら、Anypoint Exchange にパブリッシュすることができます。コードエディタの右上隅にある [Publish to Exchange (Exchange へのパブリッシュ)] ボタンをクリックして [Publish API Specification to Exchange (Exchange への API 仕様のパブリッシュ)]​ダイアログを開きます。

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub