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

2022 年 5 月 26 日に OpenAPI Generator が 6.0.0 にメジャーバージョンアップしました。

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

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

OpenAPI Generator

OpenAPI Generator は、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 Generator の 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 が採用されています (執筆時点で公開されていた最新は 6.7.0)。

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

ただ、6.0.0 で生成されたモジュールでも 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

openapi-generators/openapitools-generator-action を利用している場合は、タグ名を指定します。

オプション名は generator-tag で、タグ表記なので「v5.4.0」のように v 付きの値を指定します。

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

OpenAPI Generator 本体の挙動に大きく左右されますが、各アクションのオプションも重要です。

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

まとめ

OpenAPI Generator 6.0.0 で発生した問題と、5.4.0 にバージョンを固定する対応方法を紹介しました。

5.4.0 にも問題が全くないわけではありませんが、6.0.0 は致命的な状態だったので、いったんバージョンを戻すことにしました。

もちろん OpenAPI (Swagger) の書き方が悪いケースもあるため、自分側の改善余地も忘れずに見直したいところです。

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

saratoga

フリーランスエンジニア

XYouTube

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