1. Homepage
  2. Design Center
  3. API Designer

  4. テキストエディターでの API 仕様の作成

テキストエディターでの API 仕様の作成

API Designer のテキストエディターを使用して、RAML 0.8、RAML 1.0、OAS 2.0、OAS 3.0、AsyncAPI 2.0 で直接 API 仕様を作成できます。OAS および AsyncAPI API 仕様は、JSON または YAML ファイルとして作成できます。

始める前に

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

手順

  1. Design Center の ​[Projects (プロジェクト)]​ ページで、​[Create new (新規作成)]​ をクリックします。

  2. [New API Specification (新しい API 仕様)]​ を選択して REST API を作成するか、​[New AsyncAPI (新しい AsyncAPI)]​ を選択して AsyncAPI を作成します。

  3. [New API Specification (新しい API 仕様)]​ または ​[New AsyncAPI (新しい AsyncAPI)]​ ダイアログで、プロジェクトに名前を付けます。

    名前は後で必要に応じて変更できます (拡張子は変更できません)。

  4. REST API 仕様の作成を開始します。

    1. [I’m comfortable designing it on my own (自分でデザインします)]​ オプションを選択します。

    2. RAML または OAS 仕様を選択します。

      選択した仕様の型とバージョンを使用して、API Designer によって API 仕様のスタブが作成されます。

      デフォルトでは、API Designer によって RAML 1.0 ファイルが作成されます。プロジェクトが作成された後でファイルを RAML 0.8 または OAS に変更できます。API 仕様を作成するプロジェクトでは、RAML、OAS、その他の種類のファイルを混在させることができます。

  5. AsyncAPI 仕様の作成を開始します。

    • プロジェクト言語として YAML または JSON を選択します。

テキストエディターが開きます。

API Designer テキストエディターは以下のパネルに分かれています。

  • 左側のパネルには、プロジェクトのファイルと連動関係のリストが表示されています。

    スタブ仕様ファイルがリストされ、プロジェクトのルートファイルとして設定されます。仕様名の横にあるオーバーフローメニューアイコン (​manage dependency versions design center 018a5​) をクリックして ​[Rename (名前変更)]​ を選択すると、このファイルの名前を変更できます (拡張子は変更できません)。

    左側のパネルには、​exchange.json​ ファイルもリストされます。このファイルには、プロジェクトを Anypoint Exchange にパブリッシュするときに Exchange から要求されるメタデータが含まれます。このファイルは参照のみです。

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

    複数の仕様ファイルを作成する場合、いずれかをプロジェクトのルートファイルとして指定する必要があります。

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

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

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

  • 下部のパネルを展開すると、プロジェクトエラーが表示されます。API Governance を使用しており、編集中の API 仕様に連動関係としてルールセットが適用されている場合、​[Project Errors (プロジェクトエラー)]​ には API 仕様の機能エラーと準拠メッセージが表示されます。

エディター

エディターでの作業中には、多くのコマンドを使用して API 仕様内を移動したり、API 仕様のコンテンツを操作したりできます。​F1​ キーを押すと、これらのコマンドのリスト、およびほとんどのコマンドのキーボードショートカットが表示されます。

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

  • プロジェクトへのファイルおよび API フラグメントのインポート​

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

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

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

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

    REST API 仕様を作成するときに、指定されたエンドポイントへのコールをシミュレーションできます。

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

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

    プロジェクトはいつでも ZIP ファイルとしてエクスポートできます。テキストエディターの右上隅にある歯車アイコンをクリックして ​[Download Project (プロジェクトをダウンロード)]​ を選択します。

  • ファイルのダウンロード​

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

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

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

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

次のステップ

API 仕様が完成したら、Exchange にパブリッシュすることができます。​「API 仕様のパブリッシュ」​を参照してください。

関連情報