CursorでOpenAPIのYAMLファイル作成を半自動化できるのか？

普段のコーディング作業をしていると、単純だけど面倒な作業がよく発生しますよね。

特に、OpenAPIのYAMLファイル作成なんかは、単純なタスクだと思います。

「この面倒くさい作業、なんとか効率化できないのか…」

そんなことを考えていた時に、「Cursor（AI搭載のコードエディター）を使えば、もしかしたらこの作業が楽になるんじゃないか？」というアイデアが浮かびました。

そこで今回、実際にCursorを使って、OpenAPIのYAMLファイル作成を楽に作成できないか試してみようと思います！

結果が知りたい方は「実際に試してみて」から見ることをおすすめします。

実際に試してみる

まずはコントローラーやモデルの定義をします。

今回は、taskを一覧で取得するAPIとtaskを作成するAPIの2つを新たに作成したと仮定し、これに対応するOpenAPIのファイルを作成していきます。

OpenAPI定義の作成

まずは以下のような画像でyamlファイルを作成してみてもらいましょう。

指示出しはwith codebaseを使用（⌘+↵）しました。

このときのプロンプトにおいて意識したポイントは以下になります。

• どのような内容を作るべきかはコントローラーやモデルの定義したファイルを参照するように指示
• Anycloudでは1ファイルではなくファイルを分割してYAMLファイルを管理しているため、どこにどのようなファイルを作成したらよいかを明確にするために、entity, responseなど生成してほしいものを指定しました
• どのように書くべきかのフォーマットを理解してもらうために、既存のファイルを参照するようにしてもらいました（今回は post.yaml）

  

数秒待つと以下のように1つずつ対象のファイルに対応するコードが生成されました！

この時点では特に正しいかどうかは見ず次に進みます。

既存ファイルへの反映は出力結果上のApplyを使用し適用していきます。

新規ファイルの場合、Applyはうまく動かないためコマンドでファイルを作成しそこにコードを反映させるようにしてみましょう。

結果が以下のように出たため、Runを押し実行します。

するとYAMLファイルが無事作成できました！

OpenAPI定義から必要なファイルを自動生成

弊社のプロジェクトでは make openapi-build と叩くことで、OpenAPIの定義からAPIやクライアントサイドで必要なファイルを自動生成してくれるのでこのコマンドを実行します。

実行後に以下のようなエラーが出ました。

どうやら生成したファイルのうち、ResponseTaskListという部分に問題があるようです。

Errors:
	-attribute components.responses.ResponseTaskList.properties is unexpected
	-attribute components.responses.ResponseTaskList.description is missing
	-attribute components.responses.ResponseTaskList.type is unexpected
Warnings:
	-attribute components.responses.ResponseTaskList.properties is unexpected
	-attribute components.responses.ResponseTaskList.description is missing
	-attribute components.responses.ResponseTaskList.type is unexpected

	at org.openapitools.codegen.config.CodegenConfigurator.toContext(CodegenConfigurator.java:546)
	at org.openapitools.codegen.config.CodegenConfigurator.toClientOptInput(CodegenConfigurator.java:573)
	at org.openapitools.codegen.cmd.Generate.execute(Generate.java:433)
	at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
	at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)
make: *** [openapi-build] Error 1

ここはエラー内容を基に手動で修正し、再度 make openapi-build を叩いてみました。

その結果、無事必要なファイルが生成できたようです！

生成されたファイルの一部

無事コントローラー層のコードでもOpenAPI定義を基に生成された型が読み込まれ動いていそうです。

実際に試してみて

Cursorを使用したOpenAPIのYAMLファイル作成の半自動化を試してみました。

まず、最終的には必要なファイルの作成までCursorを活用して完了することはでき、このプロセスを通して以下のようなことを感じました。

• 初回の試行では、効率的な情報提供方法を模索する必要があったため、通常の手動作業と比較して同じかそれ以上の時間がかかりました
• 2回目以降は効率が上がり、従来の方法よりも明らかに短時間でタスクを完了できました
• さらにもっと試行錯誤することで、より精度の高い半自動化が可能になると感じました。例えば、YAMLファイルのコード記述方法での失敗を踏まえ、次回はその部分についての指示をより詳細に行うなどの改善が考えられます。

理想的には、プロジェクトのディレクトリ構成を自動的に解析し、それに適合したファイル生成を一度で行えることですが、今回の試行ではそこまでは達成できませんでした。

プロジェクトの具体的なディレクトリ構成や記述スタイルについても言及することで、より高い精度が得られる可能性があります。

総じて、Cursorを活用したOpenAPIのYAMLファイル作成の半自動化は、習熟すれば効率的なツールになる可能性を秘めています。

初期の学習曲線は存在しますが、継続的な使用により、作業時間の短縮と効率化が期待できます。

今回の実験を通してCursorを使ったコーディングの効率化はもっとできそうと感じたので、これからもどんどん実験してみようと思います！