Swaggerとは

Swaggerとは

Swagger は RESTful APIを構築するためのオープンソースのフレームワークのこと。
「Open API Initiative」という団体がRESTful APIのインターフェイスの記述をするための標準フォーマットを推進していて、それがSwagger。
日本ではまだそこまで普及していないが、海外ではデファクトスタンダードみたい。

Swaggerを使うと何がいいの？

SwaggerUIとSwaggerEditorが素晴らしいため。
SwaggerUIはSwaggerの書式（Swagger Spec）で書いておく自動的にドキュメント化してくれ、コードからドキュメント生成が可能。
また、そのドキュメントから実際のリクエストが投げられます。仕様書からテストまで出来るという優れもの！らしい…。
http://blog.takuros.net/entry/2015/12/02/082248

Swaggerのツール類と手法

主に下記のツールが提供されている。
SwaggerSpec：RESTAPIに対して Swagger の仕様に準じたドキュメント
SwaggerEditer：Swagger Spec の設計書を記載するためのエディタ
SwaggerUI：Swagger Spec で記載された設計からドキュメントをHTML形式で自動生成するツール
SwaggerCodegen：Swagger Spec で記載された設計からAPIのスタブを自動生成

また、上記ツールを使うアプローチとしては、大きく下記の２パターンがあるらしい。
■トップダウン形式
1.SwaggerEditorでSwagger Specificationを編集、定義
2.SwaggerCodegenでSwagger Specificationからソースコードを生成

■ボトムアップ形式
1.既に存在するREST APIのソースコードからSwagger Coreのアノテーションなどを使用しSwagger Specification定義
2.生成されたSwagger SpecificationをもとにSwagger UIによって、RESTAPIをドキュメント化
https://qiita.com/disc99/items/37228f5d687ad2969aa2

SwaggerEditerを使ってみる。

①SwaggerEditorを使ってみたいので、サンプルのJsonファイルをYAMLに変換
https://www.json2yaml.com/

②YAMLファイルをExcelで整形（ダミー値とかを除去）
Excelツール

③SwaggerEditor上で確認をする
http://editor.swagger.io/

他APIドキュメンテーションツールとの比較など