こんにちは。

初めてSPAをイチから作っています。前の案件もSPAでしたが、入社した時点でAPIのほとんどは実装されていました。

しかし、今回は新しい案件です。バックエンドの実装を別の人がやってるので、今はスプレッドシートでAPIをざっと決めてやり取りしていますが、Swaggerも触ってみたい。

ということで、Swaggerを触り始めた初心者の初心者による初心者のための記事です。

Swagger (OpenAPI) ？

平たくいえば、APIの仕様をドキュメントにするための仕様です。細かい説明は誰かの記事に譲ります。

仕様書を書き始めよう

API仕様書はYAMLかJSONで書きます。

最小構成は以下の通り。

swagger: "2.0"
info:
  title: "Hello World"
  version: "1.0.0"
paths:
  /:
    get:
      responses:
        200:
          description: "success"

Swagger Editorの例だとpathsが多すぎてよくわかりませんが、とりあえず「どこにアクセスすると、どんなステータスが返ってくるのか」を書きます。はじめの一歩です。今後も、pathsにpathを追加する場合はresponsesから書き始めるといいでしょう。

プレビューで見てみると、次のようになります。

プレビューからリクエストを送信しよう

生成されたドキュメントで「Try it out」ボタンをクリックすると、パラメーターの入力フォームや「Execute」ボタンが表示されて、定義したAPIにリクエストを送信できます。

デフォルトの送信先は、相対パスの / です。つまり、Swagger Editorで開いている場合は https://editor.swagger.io/ で、このままではEditorから叩いても自分たちのサーバーには送信できません。送信先を設定しましょう。

送信先の設定は host と basePath です。自分たちの環境に合わせて設定してください。

実際に設定すると以下のようになります。

swagger: "2.0"
info:
  title: "Hello World"
  version: "1.0.0"
host: "hoge.example.dev"
basePath: "/api/v1"
paths:
  /:
    get:
      responses:
        200:
          description: "success"

仕様書を拡張しよう

この記事はここまでです。

次は、pathのsummaryやparameters、responses.schemaを追記していくことになります。つまり、pathの概要と、入力、出力の詳細な定義です。

他にもinfo.description（詳細な説明）やtags、definitionsなどの仕様が山ほどありますが、それらはオプションです。とにかく初めはそれぞれのパスと入出力を書いていって、重複をtagsやdefinitionsに移していくことになるでしょう。

それでは。