テキストエディタでの API 仕様の作成
API Designer のテキストエディタを使用して、RAML 0.8、RAML 1.0、OAS 2.0 または 3.0 (JSON または YAML のいずれか) で直接 API 仕様を作成できます。
手順
-
Design Center の [Projects (プロジェクト)] ページで、[Create new (新規作成)] をクリックします。
-
[New API Spec (新しい API 仕様)] を選択します。
-
[New API Spec (新しい API 仕様)] ダイアログで、プロジェクトに名前を付けます。
名前は後で必要に応じて変更できます (拡張子は変更できません)。
-
[I’m comfortable designing it on my own (自分でデザインします)] オプションを選択します。
-
RAML または OAS 仕様を選択します。
選択した仕様の型とバージョンを使用して、API Designer によって API 仕様のスタブが作成されます。
デフォルトでは、API Designer によって RAML 1.0 ファイルが作成されます。プロジェクトが作成された後でファイルを RAML 0.8 または OAS に変更できます。API 仕様を作成するプロジェクトでは、RAML、OAS、その他の種類のファイルを混在させることができます。
結果: テキストエディタが開きます。エディタは 3 つのパネルに分かれています。
-
左側のパネルには、プロジェクトファイルのリストが表示されています。
スタブ仕様ファイルがリストされ、プロジェクトのルートファイルとして設定されます。ファイル名の右側にある 3 つのドットを右クリックして [Rename (名前変更)] を選択すると、このファイルの名前を変更できます (拡張子は変更できません)。
左側のパネルには、
exchange.json ファイルもリストされます。このファイルには、プロジェクトを Anypoint Exchange にパブリッシュするときに Exchange から要求されるメタデータが含まれます。このファイルは参照のみです。1 つのプロジェクトで複数の API 仕様や関連ファイルを作成できます。[Files (ファイル)] パネルでプラス記号をクリックして新しいファイルを作成するか、またはプラス記号の横にあるドットをクリックしてファイルをインポートします。
複数の仕様ファイルを作成する場合、いずれかをプロジェクトのルートファイルとして指定する必要があります。
-
中央パネルには、API 仕様を作成するためのエディタがあります。プロジェクトの作成時や新しい API 仕様の開始時には、プロジェクト作成時の選択に応じて、RAML または OAS 形式の仕様ファイルの最初の 2 行が表示されています。RAML から OAS、またはその逆に切り替えたい場合は、これらの行 (およびファイル名拡張子) を変更できます。
-
右側のパネルには、中央パネルに表示されている API 仕様に含まれる型やリソースのリストが表示されます。
-
API 仕様を作成します。
エディタでの作業中には、多くのコマンドを使用して仕様内を移動したり、仕様の内容を操作したりできます。F1 キーを押すと、いつでもこれらのリストが表示されます。このリストには、大半のコマンドのキーボードショートカットも表示されます。
以下のタスクも実行できます。
- プロジェクトへのファイルと API フラグメントのインポート
-
ファイルを 1 つずつ、または .zip ファイルにまとめてインポートできます。RAML 1.0 ファイル、JSON ファイル、OpenAPI Specification (OAS) 2.0 または 3.0 ファイル (JSON または YAML) がサポートされています。コンピュータ上のローカルファイルを指定するか、またはファイルがオンラインで保存されている場合は URL を指定できます。
ファイルのインポートについての詳細とインポート手順は、このトピックの最後にある「関連情報」にリンクがある「API プロジェクトへのファイルのインポート」を参照してください。
プロジェクトへの API フラグメントの追加についての詳細は、このトピックの最後にある「関連情報」にリンクがある「API 仕様プロジェクトへの連動関係としての RAML API フラグメントの追加」を参照してください。
- API コールのシミュレーション
-
API 仕様の作成中であっても、以下を指定したエンドポイントへのコールをシミュレートすることができます。
-
-
API が成功時に返す HTTP ステータスコード
-
実際の実装が返すデータの例
詳細については、このトピックの最後にある「関連情報」にリンクがある「API コールのシミュレーション」を参照してください。
- API プロジェクトまたは仕様のエクスポート
-
プロジェクトはいつでも ZIP ファイルとしてエクスポートできます。テキストエディタの右上隅にあるギアアイコンをクリックして [Download Project (プロジェクトをダウンロード)] を選択します。
- ファイルのダウンロード
-
ファイル名の右側にあるドットをクリックして [Download (ダウンロード)] を選択します。
- 別の形式でのファイルのダウンロード
-
仕様のファイル名の右側にあるドットをクリックして [Download as (名前を付けてダウンロード)] を選択します。仕様は、サポートされている他の形式のいずれかでダウンロードできます。仕様が RAML 形式であれば、OAS YAML または OAS JSON 形式でダウンロードできます。仕様が OAS 形式であれば、RAML 0.8 または RAML 1.0 形式でダウンロードできます。
このオプションを使用してダウンロードしたファイルが有効である保証はありません。このオプションの目的は、新しい仕様の開発の基礎を提供すること、または新しい形式で元の仕様の開発を継続できるようにすることです。
次のステップ
API 仕様が完成したら、Exchange にパブリッシュすることができます。「API 仕様のパブリッシュ」を参照してください。