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で、作家サポート機能が充実したようです。
僕も、サポート機能を体験してみたいです！
また僕もブログを毎週書く上で励みになります！
本当に少額でも良いので、サポート頂けたら嬉しいです。