OpenAPI定義ファイルの分割管理

ライクル開発責任者の永井です。
ライクルではRESTful APIのスキーマ定義をOpenAPIで管理し
フロントのコードを一部生成しています。
開発が進むにつれてOpenAPIの定義ファイル(yaml)の行数が甚大になってきてメンテしづらい。 そんな事案が発生してきたのでyamlファイルを分割することにしました。

分割のやり方について

ファイル内で行数をしこたま稼いでいるpathsとcomponentsを分割していくことにしました。
こちら を自前で書いて分割はすませています。 分割後は下記の構成です。

./openapi
├── root.yaml
├── components
│   ├── parameters
│   │   ├── HogeId.yaml
│   │   ├── Desc.yaml
│   │   ├── Limit.yaml
│   │   ├── Offset.yaml
│   │   ├── Order.yaml
│   │   ...
│   ├── responses
│   │   ├── Accepted.yaml
│   │   ├── BadRequest.yaml
│   │   ├── Forbidden.yaml
│   │   ├── InternalServerError.yaml
│   │   ├── NotFound.yaml
│   │   ...
│   └── schemas
│       ├── Hoge.yaml
│       ├── Hoges.yaml
│       ├── Fuga.yaml
│       ├── Fugas.yaml
│       ├── Piyo.yaml
│       ├── Piyos.yaml
│       ...
└── paths
    ├── hoges-hoge_id-fugas-fuga_id-piyos.yaml
    ├── hoges-hoge_id-fugas-fuga_id.yaml
    ├── hoges-hoge_id-fugas.yaml
    ├── hoges-hoge_id.yaml
    ├── hoges.yaml
    ...

詰まったところ

openapi-generatorでtypescript-axiosを生成すると...

  • 引数の順番が今までと変わる
    • コード修正で対応
  • parameterでarrayにしているもののurl出力結果が変わる
    • hoges=1&hoges=2&hoges=3 だったものが hoges=1,2,3に
    • ドキュメントを参考に、yamlの中でarrayのparameterに style=form, expose=trueを指定して対応

Pros/Cons

分けて間もないので今後の運用で変わるかもしれませんが、今想定しているPros/Consです。

  • Pros
    • 1ファイルの記述量が少ない
    • 1ファイルの責任範囲が明確
    • 新規エンドポイントを作る際にコピーが簡単
  • Cons
    • 一括修正したい際に少し手間がかかる

最後に

ライクル開発部では開発のボトルネックになるものを全員で議論し 日々改善をすすめています。
今後も共有をしていければと思います。