Swaggerを勉強したことまとめ

## マイクロサービス化のトレンド

- モノリシックな1つの大きなアプリケーションから、**マイクロサービス化**のトレンドに乗って比較的小さなアプリケーションを繋いでアプリケーション開発することが多くなっている。
- 特定のリソースへのAPIが多く開発されるようになり、APIの仕様(インターフェース)を**スピーディ**に、**人にわかりやすく**、作成する必要がある。

---

## APIの仕様と実装の乖離

APIの利用者（以下、APIコンシューマ）は、APIの仕様書を信じて作り込むしかないため、APIの提供者(以下、APIプロバイダ)は**仕様と実装の乖離を起こしてはならない**。
だが、、、

結構むずかしい（らしい）。。

---

さらに、

- 開発スピードを損ないたくない
- Gitでバージョン管理、変更管理したい
- 様々なAPIコンシューマが利用しやすいドキュメント形式

これらにコミットしないとAPIの利用が広まらない恐れが。。。

---

Swaggerはこうした課題に対する解決となるツールを提供する。
![スクリーンショット 2019-02-04 1.24.25-min.png](https://qiita-image-store.s3.amazonaws.com/0/56388/64dc3ba7-4132-bb34-1919-27ef852e2f58.png)

---

## swaggerとは
以下のツール群をSwaggerという。

| ツール名 | 説明 |
|:-----|:-----|
| Swagger Spec | RESTfulAPIの仕様を定義したドキュメント。jsonもしくはyaml形式。 |
| Swagger Editor | Swagger Specを書くためのエディタ。ブラウザで動きリアルタイムで構文チェックが可能 |
| Swagger UI | Swagger Specを読み込ませて人に見やすいページ（ドキュメント）を作成する。 |
| Swagger Codegen | Swagger SpecからAPIのスタブを自動生成する。 |
| Swagger Inspector | APIを検証でき、結果からSpecを自動生成も可能。 |
| Swagger Hub | 開発者向けのAPIのポータルサイト。 |

---

![swaggertool-min.png](https://qiita-image-store.s3.amazonaws.com/0/56388/2620b320-7e7c-1983-e7ed-4ab9969fa15e.png)

---

**swaggerを利用するメリット**

- API仕様を効率的かつ正確にモデル化
- API仕様を一瞬でドキュメント化
- エンジニア間のAPI仕様の共通化
- APIスタブサーバーを容易に自動生成
- 既存APIもSwaggerによる文書化可能
- 複数のドキュメントバージョンの管理
など

---

## さわってみよう!

Swaggerに必要なツールが揃っているAll-in-OneのGitリポジトリをクローンすればローカルでもすぐ試せます。

```
git clone https://github.com/elevennines-inc/swagger-all-in-one-docker-compose.git
cd swagger-all-in-one-docker-compose
docker-compose up -d
```

---

### Swagger Spec

現在、Swagegr Specは`swagger ２.0`と`swagger 3.0`の二つの構文がサポートされている。

`swagger 3.0`は`openapi 3.0`とも呼ばれ、
それに伴いopenapi 3.0で書かれている`Swagger Spec`は`OpenAPI Spec(3.0)`とも称される。
[swagger 3.0での変更点について](https://developer.ntt.com/ja/blog/fbb1636b-b3f8-47b9-ac7c-9080a5d9e7ae)

※前述したカタカナのオープンAPIとopenapiは明確に区別されているようです。

なお、2019年2月現在、ネット記事のサンプルコードは2.0と3.0の半々くらいの印象。

---

**Swagger Spec作成のアプローチ**

- １からAPI仕様を作成していく場合
 - 論理的なインターフェースモデルを検討しながら、Swagger Editorなどで作成する。
 
- 既存の実装済みAPIがある場合
 - 既存のAPIをSwagger Inspectorでコールし、結果をもとにSwagger Specを出力する。

---

**まずは無料で試せるSwagger Editorで作成してみよう**

---

### Swagger Editor

[Swagger Editor](https://swagger.io/tools/swagger-editor/)でSwagger Specを作成し、同時にSwagger UI(API仕様書)の表示を確認する。
似た機能で、[VScodeのアドイン](https://marketplace.visualstudio.com/items?itemName=Arjun.swagger-viewer)も存在する。

Swagger Specを１から作るのは大変なので、この辺りをコピペして修正していくといいかも
https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v3.0

--- 

### Swagger UI

さきほど作ったSwagger Specを読み込ませてAPI仕様をブラウザ上で確認する。
スタブサーバーや開発したAPIサーバーにリクエストを実行し、実際のレスポンスを確認できる。

自社の開発者向けのAPIドキュメントとしてはこれで十分ではないかと思う。

---

## Swagger触ってみた感想

イイネ😁

- Swagger Specをjsonとyaml両記法で書ける
- Swagger SpecからAPI仕様書が一瞬で作成できる
- APIリクエストの内容をかなり詳細に定義できる
- Gitで変更履歴管理が可能
- スタブサーバーの構築が容易になる
- クライアント側とAPI側で平行開発できる

もう少し😣

- 公式だけでも周辺ツールが多く少しとっつきにくい
- Swagger Specの独自構文を覚える必要がある
- Swaggerスタブはパスに対して固定の結果しか返せない

---

## 参考1 (オープンAPI)
ある企業が提供するAPIのうち第三者がアクセス可能なAPIのこと。

- Google Map API
- Twitter API
- [三菱UFJ銀行API](https://developer.portal.bk.mufg.jp/)
など

様々なAPIが試せる[楽天RapidAPI](https://api.rakuten.co.jp/ja/)というものも。

---

## 参考2 (jsonschema)

APIのリクエスト/レスポンスの[JsonSchema](http://json-schema.org/)というjsonの拡張定義をベースに作成されている。

JsonShemaとは
- jsonオブジェクトに注釈をつけられる
- 人間にも機械にも読める形式で記述できる
- 自動テストやjsonデータの品質検証ができる

＊個人的には、JsonSchemaは拡張性があり、機械的に扱いやすため様々な応用が聞くのではないかと思っている。

---

## 参考資料

- https://news.mynavi.jp/itsearch/article/devsoft/2395
- https://www.slideshare.net/takurosasaki/swaggerapi