マイクロサービス化のトレンド
- モノリシックな1つの大きなアプリケーションから、マイクロサービス化のトレンドに乗って比較的小さなアプリケーションを繋いでアプリケーション開発することが多くなっている。
- 特定のリソースへのAPIが多く開発されるようになり、APIの仕様(インターフェース)をスピーディに、人にわかりやすく、作成する必要がある。
APIの仕様と実装の乖離
APIの利用者（以下、APIコンシューマ）は、APIの仕様書を信じて作り込むしかないため、APIの提供者(以下、APIプロバイダ)は仕様と実装の乖離を起こしてはならない。
だが、、、
結構むずかしい（らしい）。。
さらに、
- 開発スピードを損ないたくない
- Gitでバージョン管理、変更管理したい
- 様々なAPIコンシューマが利用しやすいドキュメント形式
これらにコミットしないとAPIの利用が広まらない恐れが。。。
Swaggerはこうした課題に対する解決となるツールを提供する。
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のポータルサイト。 |
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での変更点について
※前述したカタカナのオープン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でSwagger Specを作成し、同時にSwagger UI(API仕様書)の表示を確認する。
似た機能で、VScodeのアドインも存在する。
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
など
様々なAPIが試せる楽天RapidAPIというものも。
参考2 (jsonschema)
APIのリクエスト/レスポンスのJsonSchemaというjsonの拡張定義をベースに作成されている。
JsonShemaとは
- jsonオブジェクトに注釈をつけられる
- 人間にも機械にも読める形式で記述できる
- 自動テストやjsonデータの品質検証ができる
＊個人的には、JsonSchemaは拡張性があり、機械的に扱いやすため様々な応用が聞くのではないかと思っている。