すでに開発中のAPIにOpenAPIを効率的に導入する方法

LX DESIGNでCTOしている工藤です。

LX DESIGNでは以下の記事で複業先生のフロントの大規模リファクタリングの話を公開しました。今回はそこで使ってるOpenAPIの話をしようと思います。
https://zenn.dev/lxdesign_blog/articles/c40708cdd87878
弊社のエンジニアがおもしろくフロントの全体像を書いてくれてるのでぜひ読んでください。

この中で、openapi2aspidaの話にも触れているのですが、弊社ではもともとスピードを意識しすぎていたこともありAPIドキュメントの管理はOpenAPIで管理されてない状態でした。（最初からちゃんと管理しておけばよかったなと思ってます。）
しかも、それで2年くらい開発したので大量のエンドポイントが実装されている状態でした、、
この記事では、途中から大量のOpenAPIのファイルを作成する際にどう工夫して効率化していったかをお話できればと思います。

なにを実現したかったのか

OpenAPIファイルを作ることはもちろんなのですが、時間をかけず簡単に作り、その上で今後の運用上も負債にならない状態はどんな状態か考えました。一旦以下の内容を満たせばクリアかなと思って調査を進めました。

・既存のコードを利用しながら作成することで作業を簡単にしたい
・APIとの整合性を保つようにAPIと同じGitリポジトリで管理したい
・1ファイルにすべて記載すると管理が大変になるので、responseごとなどでファイルを分割したい

OpenAPIファイルの作成ツールの検討

OpenAPIの作成については前述した

・既存のコードを利用しながら作成することで作業を簡単にしたい

でうまく効率化したかったのでツールを調べてみました。色々と調べた結果、Stoplightが既存のコードからも一部生成できて良さそうでした。
しかし、

・APIとの整合性を保つようにAPIと同じGitリポジトリで管理したい
・1ファイルにすべて記載すると管理が大変になるので、responseごとなどでファイルを分割したい

については少し扱いにくい部分がありました。Gitの管理はできたりはするのですが、APIのコードを一緒に管理するのは難しかったりしたり細かい部分は、やっぱり手作業で調整したほうが良い部分もあったのでそのへんは妥協しています。

その結果、一番最初の作る部分はStoplightで作成し、既存のエンドポイント分すべて作り終わったらファイルをエクスポートしてローカルでyamlファイルを管理することにしました

一度作ったあとはローカルのほうが細かいところにも手が届くし、VSCodeに書くことをサポートしてくれるツールはたくさんあったのでそれで十分でした。

StoplightによるOpenAPIファイルの作成

Stoplightを利用することでGUIでOpenAPIを作成していきます。yamlとかに慣れてない方からすると使いやすそうです。

基本的な使い方は、プロジェクトを作ったあとは画像にあるようなpathsやresponsesに追加していくような感じです。

これを一つ一つ追加するのは少し大変なのですが、それぞれの中身は既存のコードを元に自動で作成してくれます。
例えば、以下のようなレスポンスのエンドポイントがすでにあったとします。

{
  "id": 123,
  "name": "Sample API Response",
  "description": "This is a sample description for the API response.",
  "user_id": 456,
  "created_at": "2025-01-04T12:00:00Z",
  "updated_at": "2025-01-04T12:30:00Z"
}

本来であれば以下のように一つずつGUIでポチポチ作っていく必要があります。

ただ、既にエンドポイントが実装済みの場合はそれを渡すだけで自動で作成してくれます。
まずは、Generate from JSONというボタンを押します。

そこに先ほどのjsonを貼り付けてGenerateボタンから自動生成します。

するとこのようにすべてレスポンスを生成してくれます。

これを作成済みのエンドポイント全てで行う必要はあるのですが作業自体はかなり楽だと思います。

Stoplightでできなかったことと今後の運用について

これを繰り返すことでファイルを作成することができます。ただ、前述した通り

その結果、一番最初の作る部分はStoplightで作成し、既存のエンドポイント分すべて作り終わったらファイルをエクスポートしてローカルでyamlファイルを管理することにしました

で管理することにしたのでエクスポートして、APIを管理してるリポジトリの中に入れました。ただ、Stoplight上では分割されていたように見えていたのですが、ファイル自体は分割されておらずすべて一つのファイルでエクスポートされました。なんかいい方法があったのかもしれないのですが、調べて思った通りの分割にならなかったら結局意味がないので、そこは改めて自分で分割だけ行うようにしました。

現在の運用方法ですが、はじめに作成した分割ルールに従いVSCodeに OpenAPI(Swagger) Editorを入れて書いています。
StoplightではOpenAPI 3.1.x系で作成したのですが、OpenAPI(Swagger) Editorは3.0.x系までしか対応していなかったのでそこはちゃんと調べてなくて失敗でした。その結果コンパイルエラーが適切に表示されず書きにくい状態が発生しました。こちらはバージョンを3.0.x系にすれば問題ないので、皆さんは作成するときに気をつけていただければと思います。

実際にローカルで運用してみた中でymlファイルを書くのは、Stoplightで行ったレスポンスからの自動生成に比べると大変ではありました。しかし、この辺は生成AIとの相性が良く、弊社ではGitHub Copilotを利用しているため、すべて自分で書くことはないので大きな負荷にならずに運用できています。