ジモティーのAPI開発

ジモティーのAPI開発では、仕様の共通化を目的としてOpenAPI を導入しています。

OpenAPI は公式ドキュメントでREST APIのためのAPI記述形式として説明されており、定義ファイルをYAMLやJSONで記述することができるものです。

定義ファイル編集時はOpenAPI の GUI 定義エディタとして提供されているStoplight Studio ( バージョン2.10.0 )を使用することで、仕様の把握にかかる時間を短縮し、直感的な記述を行えるようにしています。

課題

OpenAPIの定義はyamlを1ファイル用意し、gitで管理していました。

しかし同時に編集する開発メンバーが増えたことの影響で、ファイルのコンフリクトが頻繁に発生するようになってきました。

# 開発メンバーの声
Aさん
OpenAPI のファイルはコンフリクトしやすいのが課題ですね。。。

Bさん
openapiのymlのコンフリクト解消したら関係ないpathの定義が壊れてるの腹立つ、、

このような課題感から解決策検討を行いました。

問題解消のために試してだめだった方法

ウェブでopenapi.ymlファイルの分割方法を検索すると、ファイル分割によるコンフリクト解決案がいくつかヒットします。

解決案の1つとして、以下のようなフォルダ構成を用意し分割を試しました。

Path とSchemaを分割する

root
│  openapi.yaml
│  
├─build
│      openapi.yaml
├─paths
│      users.yaml
│      user_settings.yaml
│      
└─schemas
        User.yaml
        Post.yaml
        Error.yaml

OpenAPIの用語としてpaths とschemasは以下のように説明されています。参考

paths
パスはAPIが公開する/usersや/reports/summary/などのエンドポイントのことで、これらのパスを操作するためのHTTPメソッドと一緒に記述します。

schemas
API で使用されるデータ構造を記述します。

各ファイルが分割された状態だとStoplight Studioで仕様の確認が行えないため、swagger-cli を使うことで、分割したファイルを結合します。

※ 結合ファイルは、build/openapi.yaml を指定し生成しています。

分割されたopenapi.yml を直接編集することでAPIの仕様を記載する場合は、こちらの方法でコンフリクト問題を解決できます。

しかし前述の通りジモティーのAPI開発では、openapi.ymlの編集にStoplight Studioを使用しています。

Stoplight Studioはopenapi.ymlが分割された状態では一部正しく編集を行えないためファイルは結合する必要があり、結合したファイルはStoplight Studioで編集後にコンフリクトを防ぐために分割する必要があります。

ファイルを結合するツールはswagger-cli が用意されていますが、結合されたファイルを分割するツールは見つからず、準備に時間がかかる可能性もあったため他の方法も模索することにしました。

Path 順、Schema順にぞれぞれソートする

そもそもopenapi.ymlファイルがコンフリクトする原因はPathやSchemaの最終行付近で編集が集中するからであり、PathやSchemaをそれぞれソートすることができればコンフリクトを防げる可能性は高いです。

これを踏まえ、pre-commit を導入し、commit 直前にPathとSchemaをそれぞれ確認し、ソートする方法を試しました。

pre-commit はコミットごとにスクリプトを実行し、コード上の問題を自動で指摘できるようにするツールでgit commit 時にPath とSchemaをソートするために使用します。

大まかな処理の流れ

1. 開発者がopenapi.ymlファイルの内容を追加・編集する
2. 変更内容を git commit する
3. pre-commit により.git/pre-commit ファイルに記載の処理が実行される
4. .git/pre-commit の中でソート用の 処理ファイルを実行する ( ジモティーでは ruby ファイルでソートしている)
5. 処理ファイルの中でopenapi.ymlファイルに記載されている内容をPathごと、Schemaごとに格納し、ruby のsort メソッドで処理を行う

この方法であればopenapi.ymlファイルを分割しないため、Stoplight Studioを使用しつつコンフリクトを抑えることができます。

似た名前のPath が同時に作成された場合にまたコンフリクトが発生する可能性もあるとは思いますが、コンフリクトは発生しなくなりました。