ルール
OpenAPI ファイル分割にあたって、認知負荷を下げるために以下のルールを設定しています
1. 1 API -> 1 YAML ファイル
- 配置場所は
paths/xxx/${METHOD}.yml
xxx は URL パスのフルパスで、スラッシュを _ で置換- ファイル名は HTTP メソッド ( 大文字.yml )
- 例
- GET
/hoge/foo/bar/ -> paths/hoge_foo_bar/GET.yml
- PUT
/hoge/foo/bar/ -> paths/hoge_foo_bar/PUT.yml
ファイル名が大文字の理由
- HTTP メソッドは大文字で表現されることが多い
- ファイル名を見た時、直感的に HTTP メソッドを想起することを期待
2. openapi.yml のパスとディレクトリ名を合わせる
- tree コマンドなどで一覧した時 YAML の構造と一緒にすることで、認知負荷を下げる
- 可能な限りでよい
3. component 以下のファイルの命名規則は Upper Camel にする
- 分割したスキーマファイルを利用して OpenAPI Generator で、 Kotlin コードを生成した時、ファイル名が採用されるため