【OpenAPI】Stoplight studio でAPI定義を作成する【swagger】

2023年7月15日

記事のターゲット

はじめに

記述量が多くなりがちなOpen APIをGUIで楽に記述する方法を紹介します。

まずはstoplit studioの公式サイトからGet Startedをクリックして登録を進めていきます。

メールアドレス認証を行い、プロジェクト名とGitのURLを打ち込んで始めます。ローカルで試したいだけの場合などは適当なURLを入れます。

編集画面まで進めたらAPI作成画面で新規APIを作成します。

作成すると最初にサンプルのGET、POSTの通信が作成されているので参考にしてもOK。邪魔ならタブの左上にあるDeleteボタンか左ペインの該当Pathsの欄で右クリックで削除できます。

各属性についての説明は公式Documentに乗っているので省略します。

左ペイン右クリックで追加や削除ができる。

エンドポイント(URL)が記入されている右のPath Paramsをクリックして項目欄を出現させた後に任意のパラメータを追加する。

POSTタブの中の+Add Bodyをクリックして任意のリクエストボディを追加できる。

＋Responseをクリック。追加したい分だけクリックしていけば増やしていける。右側の数値部分をクリックすることで他のステータスコードも追加できる。

objectの右にある+をクリックすることでJSONの項目を追加していける。

idが入っている部分は項目の物理名、stringが指定されている部分が型の指定部分。

クリックすることで数値や真偽値など別の型を指定することもできる。

Componentsの欄では作成したModelを指定することもできる。

Combine Schemasの欄で指定ができる。

oneOfについては以下参照。

コードの自動生成を行う場合はswagger3.0以降のものを使用しないと~Of系の定義をきちんと書いてくれないので注意。

エクスポートしたいファイル上で右クリック。

Exportをクリック。

好きなフォーマットを指定してSave to file をクリック。　X-Extensionsを含めると自動で生成される追加ヘッダが同時に出力されます。