tl;dr

Web APIを公開しているサービスでは、開発者向けにドキュメントも公開する必要がある

サービスが進化するのに合わせてAPIにも変更を加え、その都度ドキュメントも改修する必要があるが手作業でメンテナンスを行うのはコストがかかるし漏れが生じる可能性もある

SwaggerはWeb APIを公開する開発者向けのツールであり、JSONやYAMLで定義ファイルを書くだけで、ドキュメントを自動で作成することができ、さらに定義ファイルを使用したバリデーションもできる

Swaggerとは

簡単にAPIの開発やメンテナスを行うためのツールセット

APIの開発者は、OpenAPI Specification (OAS)と呼ばれるREST API向けのフォーマットに合わせて、JSONかYAMLファイルを作成する

フォーマットはGithubに公開されている

2019/1/6時点の最新版は3.0.2

作成した定義ファイルを他のツールに読み込ませることで、APIの公開やメンテナンスを簡単に行うことができる

定義ファイルからどのようなドキュメントが生成されるかを確認できるブウラザベースのエディタ

定義ファイルを変更しながらリアルタイムに成果物を確認することができる

VSCodeやJet BrainsなどメジャーなIDEではプラグインも用意されている

定義ファイルを読み込ませることでドキュメントページのHTMLを作成してくれるツール

各エンドポイントへのリクエストに必要なパラメータなどが記載してあり、さらに「try it out」と書いてある部分をクリックすることで、ドキュメントページ上で実際にAPIリクエストを送ることができる

定義ファイルを読み込ませることで、公開したAPIを使って別サービスを開発するディベロッパー向けのSDKを簡単に作成することができる

Swaggerを使えばyamlやjsonを書くだけでAPIの半分が完成する世界を作ることができるらしい

初めてAPI callするときとか単純なtypoで失敗したり、parameterが多いリクエストとかはcurlで試すのもなかなかめんどくさいのでSwagger UIはAPIの開発者だけでなく、APIの利用者にとってもかなり価値のあるツールだと思う