Swaggerとは
REST API を設計・開発するために使用するツールスイートです。
※スイートとは、「一式」や「ひとそろい」などという意味です。ツールスイートとは、「ツール一式」や「ツールがまとまったもの」という意味です。
以下のようなエディターにより、REST API を記述することができます。
画像引用元：
画面左側で API の仕様を記述します。記述するとリアルタイムで画面右側の UI が更新されます。この UI を Swagger UI と呼びます。
画像引用元：
このような API の記述方法を定めている仕様のことを Swagger 仕様と呼びます。ただし、2015年に Swagger は OpenAPI に寄贈され、現在では Open API 仕様（OpenAPI Specification）と呼びます。OpenAPI 仕様はその頭文字から OAS とも呼ばれます。
画像引用元：
OpenAPI は、REST API のオープンソースプロジェクトであり、OpenAPI Initiative によって管理されています。OpenAPI Initiative は Linux Foundation に所属する団体です。MicrosoftやGoogle、IBMなどが支援しています。
画像引用元：
画像引用元：
厳密には OAS の YAML 形式（JSON形式もサポート）のドキュメントのことを OpenAPI Description （OAD）と呼びます。OAD は OAS に基づいて記述されます。
画像引用元：
Swagger UI の使い方
Swagger UI では作成した OAD を検証することができます。ここでいう検証とは、OAD 内の GET や POST を試しに実行してみるという意味です。
このような検証ツールとして POSTMAN が有名です。
Swagger UI ではローカルホストに立てたサーバにリクエストを送信することができます。より詳細には、Swagger UI のエクスポート機能により、サーバを立てるためのソースコードをダウンロードし、ローカルで実行するという形です。このソースコードのプログラミング言語は以下のように選択することができます。ここでは Python を選択しました。
ダウンロード後、README に記載されているコマンドを実行し、ローカルホストにサーバを立てます。
pip3 install -r requirements.txt // 必要なパッケージをインストールする
python3 -m swagger_server // ローカルホストにサーバを立てる
実行するコマンドは以下の Usage に記載されています。
ローカルホストにアクセスすると、記述した OAD から生成された Swagger UI が表示されます。
Python の場合、以下のファイルを編集することでサーバのレスポンスを変更することができます。
[ダウンロードしたフォルダ名]/swagger_server/controllers/default_controller.py
このようにモックサーバでリクエストやレスポンスを検証しつつ、API の基となる OAD を編集することができます。Pythonでは、以下のファイルが OAD です。
[ダウンロードしたフォルダ名]/swagger_server/swagger/swagger.yaml
ソースコードや OAD を編集したら、ブラウザの更新だけでは編集内容が反映されないため、一度サーバを立て直す必要があることに注意します。すなわち、実行中のプログラムを停止（Ctrl + C など）し、再度プログラムを実行します。
$ python -m swagger_server
OAD の書き方
ここでは説明しませんが、公式ドキュメントのリンクを貼ります。
- 入門向けのドキュメント
- すべての仕様を網羅するドキュメント