OpenAPI3へのスキーマファースト開発移行(ツール編)
スキーマファースト開発をプロジェクトへ導入してから1年が経ちました。
ツール編では移行の方針や使用ツールについて書いていきます。
Prerequisite 
- Rails + vue.jsのSPA開発
- TDD導入済み
Tools 
Why 
- SPA開発においてAPIとクライアントの開発を行っていましたがチーム開発においてAPI実装への依存度が高かった
- チームメンバーが増えてくるとAPI仕様の共有や変更の共有にコミュニケーションコストが増えてきた
- API仕様書を正にして変更があれば自動テストをFailさせたい
Purpose and Rules 
- API・クライアントの実装効率化
- RESTful API準拠及びOpenAPI3に仕様準拠
- YAMLで管理
- API仕様書の分割と結合
- YAMLのAPI仕様書を読み込み自動テスト(API/クライアント)
- API仕様書からhtmlドキュメントを生成
- (モックサーバー起動)
Tools詳細
OpenAPI3
Swagger Editor
- Swagger Editor
- VSCode Swagger Viewer
- エディタはなんでも良いですが最終的に生成したAPIがvalidかどうか確認する必要があります
multi-file-swagger
- multi-file-swagger
- APIのPathsやComponentを共通化、リポジトリ管理するために分割をしています。分割したYAMLファイルを結合するために使用しています
- プロジェクトでは自動テスト直前に自動結合させて常に最新の仕様書でテストを走らせています。
OpenAPI Generator
- OpenAPI Generator
- API仕様書のhtmlドキュメントを生成するために使用
- 一部OpenAPI3の構文に対応していない箇所がありOpenAPI Generatorに合わせた書き方をする必要があります。
- プロジェクトではCIでテストがGreenになったら最新のhtmlドキュメントをS3にアップロードし開発者以外がAPI仕様を閲覧できる状態にしています。
committee
- committee
- API仕様書をもとにリクエスト/レスポンス形式をチェックするライブラリです。現在も開発が活発でOpenAPI3に対応したのをきっかけに導入を決めました。
まとめ
- 次回はスキーマ分割とAPI/クライアントの自動テストを書きたいと思います