swagger

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

More than 1 year has passed since last update.

社内で行われた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にもたくさん投稿があるので参考になる。
日本語の書籍とかはまだなさそう。