こんにちは。
初めて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に移していくことになるでしょう。
それでは。
公式サイト: https://swagger.io/
この記事は私の個人ブログからの転載です。