何番煎じかわかりませんが、Swagger自体の使用がいくつか変わっていたりしていたので備忘録も兼ねて再度まとめて見たいと思います。
（参考）
Swaggerとは？
OpenAPIの仕様に基づいて設計された、オープンソースのツール群の名称になります。
OpenAPIとは、いわゆるRESTful APIを記載するためのフォーマットです。
Swaggerの特徴の一つとして、JSON形式で記載できることが挙げられます。
Swaggerのシリーズとしてよく使われるものは以下の３つです。
| 名前 | 概要 |
|---|---|
| Swagger Editor | ブラウザでAPI仕様書を書くためのエディタ、 Dockerイメージも配布されており、ローカルでの実行も可能。 |
| Swagger UI | API仕様書からドキュメントを生成するツール |
| Swagger Codegen | API仕様書からコードを生成するツール |
開発手法
主要な開発手順としては、以下二つのものがあるようです。
トップダウン形式：
- SwaggerEditorでSwagger Specificationを編集、定義
- SwaggerCodegenでSwagger Specificationからソースコードを生成
ボトムアップ形式
- 既に存在するREST APIのソースコードからSwagger Coreのアノテーションなどを使用しSwagger Specification定義
- 生成されたSwagger SpecificationをもとにSwagger UIによって、RESTAPIをドキュメント化
競合ツール
OpenAPIの仕様に基づくツールとしては、他はRamlとAPI BluePrintが有名どころである。
Raml
RESTful API Modeling Languageの略でその名の通りREST APIを設計するための言語。
その名より連想される通りYamlで記載することが可能である。
API BluePrint
コンセプトは「シンプルで簡潔かつ表現力が豊か」というイメージである、OpenAPI記載言語の一つ。
こちらは標準の記載言語はMarkdownである。
あまりに自由に書け過ぎてしまうため、注意しないと肥大化したプロジェクトの場合は管理が大変になる可能性がある。
Swagger Editorの部分について後ほど追記予定