API設計ツール「Swagger」が素晴らしい
今更という人もいるだろうが、先週API設計ツール「Swagger」を使ってみた。
APIベースの設計は、サーバとフロントを分けて開発する方式だけでなく、スマホアプリの開発など応用の幅は広いのではないだろうか。
API設計ツールとしては、
・Swagger
・API Blueprint
・Raml
があるようだ。
しかし、SwaggerはAWS API Gatewayでも採用されており、デファクト・スタンダードに近い状態のようだ。
今回はSwaggerの良いところや使い方について、解説したいと思う。
Swaggerとは
Swaggerは、APIドキュメント設計やAPIモックのリクエストを投げることが出来るAPI構築フレームワークである。
前述の通り、AWS API Gatewayでは、Swaggerフォーマットをインポートし、スタブを作ることも可能です。
Swaggerのツールとしては大きく4つある。
基本的には、Swagger EditorでAPI仕様をYaml形式で定義し、それを自動的にドキュメント化していくれるというツールだ。
ドキュメントからモックのURL等も定義出来るので、設計の早い段階でAPI定義することが出来、設計者とエンジニアの認識漏れを防ぐことが出来る。
参考サイト：
・Swagger 定義をインポートしてエッジ最適化 API をセットアップする
・Swaggerの概要をまとめてみた
Swaggerのメリット・デメリット
＜メリット＞
・Yaml形式のため（JsonやMarkdown形式より）管理・運用しやすい。
・APIファーストで設計すると、フロント仕様の手戻りがなくなる
・API仕様がバージョン管理可能
＜デメリット＞
・Swagger独特の記法を覚える必要がる
・周辺ツールが多く、自社に合った環境の構築が難しい
参考サイト：
・「Swaggerを利用した新規サービス開発」というタイトルで登壇して来ました
・開発効率を上げる！Swaggerで作るWEB APIモック
Swagger環境の構築
Swaggerを使うためには3つの環境があるようだ。
①Swagger HubというPaasを利用
②AWS API GatewayというPaasを利用
③SwaggerCodegenなどを使って自前でサーバ構築
＜①SwaggerHubを利用＞
メリット：
・チーム管理が出来る
・APIモックサーバをホスティング可能
・API仕様をGithubに連携可能
デメリット：
・上記のホスティングやGithubを使うためには月額90ドル〜／5Userとコストが高い
＜②API Gatewayを利用＞
メリット：
・安価にホスティング可能
デメリット：
・Swagger記法と、API Gatewayでサポートされている記法が微妙に違い簡単にインポート出来ない。
＜③自前でサーバ構築＞
メリット：
・YAMLをロードするだけでサーバが作れる
・Swaggerコードをそのまま利用可能
デメリット：
・自前でサーバを構築する必要がある
今回、①のSwaggerHub無料版と②のAPI Gateway環境を構築してみたが、①は価格、②は記法の問題で苦労した。
やはりちゃんと使いたいなら③の自前サーバ構築が必要だと感じた。
まとめ
今回はAPI設計ツール「Swagger」について解説した。
Swaggerは、Microsoft・Google・IBMなど立ち上げたAPI記述標準を目指す「Open API Initiative」がSwaggerベースにすると広報しており、AWSもAPI Gatewayで対応したところから、API仕様の標準になりつつある。
実際エコシステムもかなり発達しており、SwaggerからRailsやSpringなどのフレームワーク用のモックコードをダウンロード可能だ。
いまはAPI Gatewayなどで少し手間取ることもあるが、今後ますますAPI仕様の標準になるのではないだろうか。
もし僕の理解が違うようだったら、ぜひツイッターなどで教えて欲しいです。
最後にお願いです。
Noteで、作家サポート機能が充実したようです。
僕も、サポート機能を体験してみたいです！
また僕もブログを毎週書く上で励みになります！
本当に少額でも良いので、サポート頂けたら嬉しいです。
いいなと思ったら応援しよう！
