Swagger使ってみた

# Swaggerとは

REST API を設計・開発するために使用するツールスイートです。
※スイートとは、「一式」や「ひとそろい」などという意味です。ツールスイートとは、「ツール一式」や「ツールがまとまったもの」という意味です。

以下のようなエディターにより、REST API を記述することができます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/621414/cacce418-6d6a-7632-61af-ae60116bb532.png)

画像引用元：

https://editor.swagger.io/

画面左側で API の仕様を記述します。記述するとリアルタイムで画面右側の UI が更新されます。この UI を Swagger UI と呼びます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/621414/05a3f3be-2fb4-262d-18cd-5cd48860d118.png)

画像引用元：

https://swagger.io/tools/swagger-ui/

このような API の記述方法を定めている仕様のことを Swagger 仕様と呼びます。ただし、2015年に Swagger は OpenAPI に寄贈され、現在では Open API 仕様（OpenAPI Specification）と呼びます。OpenAPI 仕様はその頭文字から OAS とも呼ばれます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/621414/c53c1991-12c7-4472-34c4-174447a760d3.png)

画像引用元：

https://swagger.io/resources/open-api/

OpenAPI は、REST API のオープンソースプロジェクトであり、OpenAPI Initiative によって管理されています。OpenAPI Initiative は Linux Foundation に所属する団体です。MicrosoftやGoogle、IBMなどが支援しています。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/621414/e11ddb31-c101-5a65-6483-34439523d0d6.png)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/621414/98832452-9f4b-dbc3-3dc8-052b003206dd.png)

画像引用元：

https://www.openapis.org/faq

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/621414/1a1cd9b2-54ee-c19a-49d0-31e4e67c5412.png)

画像引用元：

https://www.linuxfoundation.org/press/press-release/the-linux-foundation-and-open-api-initiative-announce-agenda-for-apistrat-the-api-strategy-practice-conference


厳密には OAS の YAML 形式（JSON形式もサポート）のドキュメントのことを OpenAPI Description （OAD）と呼びます。OAD は OAS に基づいて記述されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/621414/ae1a2e15-1bf0-44c2-d253-d9277c7a0a4d.png)

画像引用元：

https://learn.openapis.org/introduction.html

# Swagger UI の使い方

Swagger UI では作成した OAD を検証することができます。ここでいう検証とは、OAD 内の `GET` や `POST` を試しに実行してみるという意味です。

このような検証ツールとして POSTMAN が有名です。

https://www.postman.com/

Swagger UI ではローカルホストに立てたサーバにリクエストを送信することができます。より詳細には、Swagger UI のエクスポート機能により、サーバを立てるためのソースコードをダウンロードし、ローカルで実行するという形です。このソースコードのプログラミング言語は以下のように選択することができます。ここでは Python を選択しました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/621414/954887d1-9b92-737b-8a41-e95667e4b5aa.png)

ダウンロード後、README に記載されているコマンドを実行し、ローカルホストにサーバを立てます。
```
pip3 install -r requirements.txt // 必要なパッケージをインストールする
python3 -m swagger_server // ローカルホストにサーバを立てる
```

実行するコマンドは以下の Usage に記載されています。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/621414/365daaa2-6732-c297-fe7c-827b6f03041d.png)

ローカルホストにアクセスすると、記述した OAD から生成された Swagger UI が表示されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/621414/90ba8a1c-d17c-df3f-9032-545686cfeb46.png)

Python の場合、以下のファイルを編集することでサーバのレスポンスを変更することができます。

`[ダウンロードしたフォルダ名]/swagger_server/controllers/default_controller.py`

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/621414/6b7de168-ca44-7bf9-42f6-f0f95ead106a.png)

このようにモックサーバでリクエストやレスポンスを検証しつつ、API の基となる OAD を編集することができます。Pythonでは、以下のファイルが OAD です。

`[ダウンロードしたフォルダ名]/swagger_server/swagger/swagger.yaml`

:::note warn
ソースコードや OAD を編集したら、ブラウザの更新だけでは編集内容が反映されないため、一度サーバを立て直す必要があることに注意します。すなわち、実行中のプログラムを停止（`Ctrl + C` など）し、再度プログラムを実行します。

`$ python -m swagger_server`

:::

# OAD の書き方

ここでは説明しませんが、公式ドキュメントのリンクを貼ります。

- 入門向けのドキュメント

https://learn.openapis.org/specification/

- すべての仕様を網羅するドキュメント

https://spec.openapis.org/oas/v3.1.0