Swagger初心者向け勉強会に参加してきたので、知ったことをメモ

社内で行われたSwagger初心者向け勉強会に参加してきたので、知ったことをメモ

Swaggerとは (https://swagger.io/)

・RESTful APIを使用する上で世界で最も支援してくれるAPIツール
・OSS標準準拠
DESIGN：エディター（http://editor.swagger.io/）
BUILD：コード生成
DOCUMENT：仕様書生成
の3要素でできている
日本ではまだそこまで普及していないが、海外ではデファクトスタンダードであるらしい
なので、ドキュメントは海外のものの方が充実している。

DESIGN

APIの設計をエディターでパワフルにやってくれる。
YAML形式のエディターを書くとドキュメントがリアルタイムで作成されていく。リアルタイムレンダリング。
コードアシスト機能がついているので、タイプセーフ。

BUILD

定義ファイルからコードが生成できる
コマンドラインで仕様書をinputにgenerateするとコードが生成される（コマンド叩くだけでコード自動生成）

DOCUMENT

定義ファイルから仕様書を生成してくれる
コードを直しても仕様書に反映される（アノテーションに合わせた内容になる）ので、常にコードと仕様書の整合性が取れている。

Swaggerのいいところ

Spring、JAX-RS、Servlet(PureJava）に対応
定義ファイルがYAMLなので、YAMLの書き方さえ覚えればどこでも共通に使える（バージョン管理も容易）
コードにアノテーションを付与することで仕様書が研ぎ澄まされていく
Excelで仕様書書いて、コード書いて、コードに修正入ったら仕様書も直してーみたいのがなくなる

個人的感想

APIのmockとして使えそう。
画面だけ作って、サーバのスタブとして使えそう。

勉強法は？

公式リファレンスは海外でデファクトスタンダードなので、充実している。
Qiitaにもたくさん投稿があるので参考になる。
日本語の書籍とかはまだなさそう。