【OpenAPI Generator】バージョン6.0.0でJavaのビルドが通らないので5.4.0に戻す

2022 年 5 月 26 に OpenAPI Gnerator が 6.0.0 にメジャーバージョンアップ。

GitHub Actions で動かしていた、openapi-generator-generate-action の参照先のバージョンも変更になってました。
(デフォルトは latest だったため)

今回は、このバージョンアップによって Java の generate ファイルのビルドが通らなくなったので、バージョン指定して 5.4.0 を使うようにしました。

この方法を紹介していきます。

OpenAPI Generator

OpenAPI ジェネレータは、OpenAPI 2.0 や 3.x のドキュメントから以下のモジュールを生成するツールです。

例えば、API の設計を Swagger に出力していた場合、その Swagger 定義から API クライアントを生成することができるのです。

API 利用者にとっては、モデルやクライアントがすぐに使えるので、API の仕様書と睨めっこする必要はありません。

多くのプログラム言語にも対応しているので、API のサービス提供側としても非常に助かります。

openapi-generator-generate-action

冒頭でも書きましたが、「craicoverflow/openapi-generator-generate-action@v1」の参照先のバージョンは「latest」なんですよね。

今のところ、このアクションを利用していますが、Java 以外では大きな問題は確認していません。

できれば自動生成したコードに手を加えたくないですが、ビルドエラーなどで動かないところは渋々ソースコードを置換しています。

Javaで発生していたエラー

OpenAPI ジェネレータの 6.0.0 が登場したのに気付いたのは、他の言語でモジュールの自動生成をしていた時。

VERSION ファイルの中身が「5.4.0」ではなく「6.0.0」になっていたからです。

そのプログラム言語でも Enum の定義がモジュール間で重複して問題があったのですが、Java はビルドが通らない深刻な状態に・・・。

Could not resolve all dependencies for configuration ':hoge:runtimeClasspath'.
> Failed to apply plugin 'com.diffplug.spotless'.
> Could not create an instance of type com.diffplug.gradle.spotless.SpotlessExtensionImpl.
> The task 'spotlessInternalRegisterDependencies' (com.diffplug.gradle.spotless.RegisterDependenciesTask) is not a subclass of the given type (com.diffplug.gradle.spotless.RegisterDependenciesTask).

以下の行にヒントがありそうなので、com.diffplug.gradle.spotless のライブラリを調べることに。

com.diffplug.gradle.spotless は Gradle のコードフォーマッターで、com.diffplug.spotless は多くの言語に対応しています。

OpenAPI Generator が 5.4.0 の時は、「com.diffplug.spotless」は 5.17.1 でした。

OpenAPI Generator 6.0.0 では、「com.diffplug.spotless」の 6.3.0 が採用されています。
(2022 年 6 月 8 日現在の最新は 6.7.0)

この変更が直接的な問題というわけではないのですが、複数のモジュールで generate されたバージョンが異なったことが影響したようです。

ただ、6.0.0 で generate されたモジュールで import が足りなかったり、利用できないクラスのメソッドが使われていたりと、どちらにしてもビルドが通らない・・・。

結局 5.4.0 に戻すことにしました。

Actionのオプションでバージョンを指定する

ということで、openapi-generator-generate-action の場合は version というオプションが指定可能です。

- name: Generate
  uses: craicoverflow/openapi-generator-generate-action@v1
  with:
    generator: "java"
    version: "5.4.0"
    config: "config.yml"

openapitools-generator-action

openapitools-generator-action のアクションを利用している場合はタグ名を指定します。

オプション名は「generator-tag」ですね。

タグなので、v5.4.0 が該当するでしょうか。

- name: Generate 
  uses: openapi-generators/openapitools-generator-action@v1
  with:
    generator: java
    generator-tag: v5.4.0
    config-file: config.yml

OpenAPI ジェネレータの挙動に大きく左右されますが、各アクションのオプションも重要。

公式のドキュメント読んで、自分のプロジェクト構成に合わせた設定にできるといいですね。

まとめ

OpenAPI ジェネレータの 6.0.0 で問題が発生したことについて紹介してきました。

5.4.0 で問題がなかったわけではありませんが、6.0.0 は致命的な問題があったのでバージョンを戻すことに。

また次期バージョン(6.x)が出た時に修正されていることを期待しています。

もちろん OpenAPI(Swagger など)の書き方が悪いケースもあるので、自分に対する反省の意味も込めて・・・。

なお、swagger が springfox から springdocs-openapi に変更になりましたが、今のところ問題なく利用できています。

saratoga

フリーランスエンジニア

TwitterYouTubeContact

仕事にも趣味にも IT を駆使するフリーランスエンジニア。技術的な TIPS や日々の生活の中で深堀りしてみたくなったことを備忘録として残していきます。