【GitHub Actions】openapi-generator-generate-action を npx 実行に置き換える方法

GitHub Actions で OpenAPI クライアントの自動生成に craicoverflow/openapi-generator-generate-action を使っていると、最近こんな警告メッセージが出るようになっていませんか。

Node.js 20 actions are deprecated. The following actions are running on Node.js 20 and may not work as expected: actions/checkout@v4, craicoverflow/openapi-generator-generate-action@f5cb8c4751e164eab904995688909966bd1f36eb. Actions will be forced to run with Node.js 24 by default starting June 2nd, 2026. Node.js 20 will be removed from the runner on September 16th, 2026.

原因は、GitHub Actions のランナー側で Node.js 20 が deprecated 扱いになり、Node.js 24 への強制移行が予定されていること。

そして残念ながら、このアクション自体は数年前からメンテが止まっており、Node.js 24 対応版が出る見込みはありません。

本記事では、メンテ停止しているアクションを廃止して、npx 経由で openapi-generator-cli を直接実行する方式へ移行する手順を解説します。

以前、このアクションの version オプションで OpenAPI Generator のバージョンを 5.4.0 に固定した話を書いた続編にあたります。

GitHub Actions の Node.js 20 deprecation で何が起きているか

deprecation のスケジュール

冒頭の警告メッセージにも含まれていますが、改めてスケジュールを整理しておきます。

• 2026 年 6 月 2 日: Node.js 24 が強制適用される
• 2026 年 9 月 16 日: Node.js 20 がランナーから削除される

craicoverflow/openapi-generator-generate-action の状況

問題のアクションを覗くと、リリース履歴は 2022 年 2 月の v1.2.1 が最後です。

action.yml の中身も Node.js 12 ランタイム指定のままで、明らかにメンテが止まっています。

# action.yml の抜粋
runs:
  using: 'node12'
  main: 'dist/index.js'

GitHub Actions の Node.js ランタイムは過去に何度も deprecation サイクルを経ています。

• Node.js 12 → 16 (2023 年)
• Node.js 16 → 20 (2024 年)
• Node.js 20 → 24 (2026 年)

これまでは GitHub 側の互換レイヤーで動いていましたが、ランタイム自体が削除されるとアクションが起動しなくなります。

openapi-generator-generate-action の中身を確認する

移行先を検討する前に、このアクションが実際何をしているのか中身を確認します。

リポジトリの src/main.ts を見ると、本質的にやっていることはわずか数行でした。

// src/main.ts (抜粋)
const openApiGenerator = 'npx @openapitools/openapi-generator-cli';
await exec.exec(openApiGenerator, ['version-manager', 'set', version]);

// 引数を組み立てて...
await exec.exec(openApiGenerator, generateArgs);

つまり、npx @openapitools/openapi-generator-cli を呼ぶだけの薄いラッパーです。

であれば、わざわざフォークして自前メンテせず、workflow から npx を直接実行すれば同等のことができるはずです。

npx 実行に置き換えたワークフローの例

結論として、こんな構成に置き換えました。

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: '24.x'

      - name: Setup Java
        uses: actions/setup-java@v5
        with:
          distribution: 'zulu'
          java-version: '17'

      - name: Generate
        run: |
          npx --yes @openapitools/openapi-generator-cli generate \
            -g java \
            -i docs/swagger/api.yaml \
            -o build/generated \
            --config openapi-generator/config.yaml

旧アクションが内部でやっていた処理を、3 ステップに分解した形です。

なぜ Node と Java の両方が必要なのか

openapi-generator-cli の挙動を整理しておきます。

• Node.js: npx で openapi-generator-cli (npm パッケージ) を実行するため
• Java: 内部で OpenAPI Generator 本体の JAR ファイルを呼び出すため (JDK 11+ 必須)

ubuntu-latest ランナーにはデフォルトで Java は入っていますが、バージョンが変わることがあるため、明示的に setup-java で固定するほうが安全です。

distribution はどれを選ぶか

actions/setup-java の distribution には、temurin / zulu / corretto などいくつかの選択肢があります。

openapi-generator-cli の実行のように 短時間で JAR を呼び出すだけの用途であれば、どの distribution でも事実上動作差はありません。

選定基準としては、プロジェクト内の他 workflow と揃えるのが運用負荷的に合理的です。

実際に切り替え前後で生成物に差分が出ないかを CI 上で diff 比較したところ、temurin と zulu で生成結果は完全一致しました。

openapi-generator のバージョンを openapitools.json で固定する

前作で書いた「version オプションで 5.4.0 に固定する」という運用は、新方式では別の仕組みで実現します。

openapitools.json の役割

openapi-generator-cli はリポジトリ直下にある openapitools.json を自動で参照する仕様です。

{
  "$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json",
  "spaces": 2,
  "generator-cli": {
    "version": "7.22.0"
  }
}

この version で OpenAPI Generator (Java 本体) のバージョンが固定されます。

例として 7.22.0 を指定していますが、利用しているプロジェクトに合わせて任意のバージョンを指定してください。

前作で 5.4.0 に固定していた方はそのままの値を入れれば、これまでと同じバージョンで運用を継続できます。

このファイルが存在しない場合は最新版が取得されますが、commit しておくことで予期せぬバージョンアップを防げます。

openapitools.json は commit すべきか

公式ドキュメントでも明記されている通り、openapitools.json はリポジトリに commit するのが基本方針です。

commit する場合のメリットは次の通りです。

• チームメンバー全員が同じ generator バージョンを使える
• CI でも同じバージョンが固定で使われる
• バージョン更新時は 明示的な PR として履歴に残る

逆に .gitignore に追加するケースは、生成だけに使う一時ファイルだと割り切る場合などに限られます。

その場合は workflow 側で --version 相当を毎回明示する設計が必要になります。

旧アクションの挙動との違い

注意点として、旧アクションは内部で「version-manager set」を呼んで、openapitools.json の中身を実行時に書き換えていました。

仮に旧アクションで version オプションを「latest」(デフォルト)のまま使っていた場合、毎回最新版が openapitools.json に上書きされて commit される状態になります。

実際、手元のリポジトリでこの挙動が動いていた CI のコミット履歴を確認すると、数週間おきに openapitools.json の version フィールドが自動でマイナーバージョンアップしていく様子が記録されていました。

気付かないうちに generator が更新され、生成コードに微妙な差分が混入し続けていた、ということです。

新方式の npx 実行では「version-manager set」を呼ばないため、openapitools.json の内容はそのまま使われます。

意図せぬバージョンアップで生成コードに差分が混入するリスクが減るので、むしろ運用しやすくなる方向の変更と言えます。

移行のチェックリスト

移行後に旧方式と挙動が変わっていないか確かめるには、テスト用リポジトリで両方の workflow を走らせて diff を取るのがおすすめです。

同じ swagger を入力にして、旧方式と新方式で生成されたファイルを比較するだけで、移行のリスクを事前に把握できます。

同じように craicoverflow/openapi-generator-generate-action を使っている方向けに、移行時に押さえておきたいポイントをまとめておきます。

• actions/setup-node で Node.js 24 (もしくは現行 LTS) を入れる
• actions/setup-java で zulu (もしくは社内標準) の JDK 11 以上を明示する
• npx –yes @openapitools/openapi-generator-cli generate … を run ステップに置く
• openapitools.json を作って generator-cli の version を明示する
• 移行前後で生成コードに差分が出ないか、テスト用リポジトリで diff 比較する

特に最後の diff 比較は、Java のように generator のバージョン差で破壊的変更が起きやすい言語では必須だと感じました。

まとめ

craicoverflow/openapi-generator-generate-action は便利でしたが、メンテ停止と Node.js 20 deprecation が重なり、移行を検討するタイミングが来ています。

幸い中身は薄いラッパーだったので、npx で openapi-generator-cli を直接実行する方式に切り替えれば、機能を維持したまま deprecation 警告を解消できます。

同じパターンは、メンテが止まっている他のサードパーティアクション全般にも当てはまります。

action.yml を覗いて「using: ‘node12’」や「using: ‘node16’」と書かれていたら、移行候補としてチェックする習慣をつけたいところです。

saratoga

フリーランスエンジニア

XYouTube

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