![スクリーンショット_2017-12-04_20.52.06](https://assets.st-note.com/production/uploads/images/5350035/rectangle_large_007c89ed9b11cef1cb080faeb7c4c6d0.jpg?width=1200)
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で、作家サポート機能が充実したようです。
僕も、サポート機能を体験してみたいです!
また僕もブログを毎週書く上で励みになります!
本当に少額でも良いので、サポート頂けたら嬉しいです。
サポート頂けたら、意味のあるnoteだったのだと励みになります。 サポート頂いたお金は、コミチの漫画家のサポートに利用させて頂きます。