🦆

Java 17、Gradle、Spring Boot 3.2 で OpenAPI Generator によるクライアントコード生成

2024/02/18に公開

Gradle

はじめに

この記事では、アプリケーションのプログラムと OpenAPI Generator で生成されたコードを同一のリポジトリで管理する構成を取り上げます。具体的には、build.gradle の設定に焦点を当て、その作成方法について解説します。

プロジェクトのディレクトリ構造は以下のようになります。

.
├── main
│   ├── java
│   │   └── com
│   │       └── monohashika
│   │           ├── application/
│   │           └── openapis/
│   └── resources
│       ├── application.yaml
│       └── openapis
│           └── sample-api.yaml
└── build.gradle

公式ドキュメント

Java クライアントコード生成に関する情報

build.gradleに設定

ここでは、OpenAPI Generator の設定を build.gradle に追記する方法を紹介します。

1: プラグインの指定
OpenAPI Generator のプラグインを追加します。

plugins {
  ...
  id 'org.openapi.generator' version '7.3.+'
  ...
}

2: openApiGenerateブロックの設定
必要な設定を openApiGenerate ブロックに記載します。

openApiGenerate {
    generatorName = “java”
    inputSpec = “${rootDir}/src/main/resources/openapis/sample-api.yaml”
    outputDir = “${rootDir}/tmp/openapis/sample-api”

    modelPackage = “com.monohashika.hello.openapis.sample-api.model”
    apiPackage = “com.monohashika.hello.openapis.sample-api.controller”
    configOptions = [
            library: "resttemplate",
            useJakartaEe: 'true',
            dateLibrary: "java8",
            hideGenerationTimestamp: "true",
            apis: "",
            apiTests: "false",
            models: "",
            modelTests: 'false',
    ]
}

Java や Spring Boot のバージョンに応じて、Jakarta EE に対応する場合は useJakartaEe を true に設定します。

Gradle タスクの実行と結果の確認

以下のコマンドで Gradle タスクを実行し、コードを生成します。

./gradlew openApiGenerate

生成されたファイルは以下の構造を持ちます。

tmp
└── openapis
    └── sample-api
        ├── .github
        ├── .openapi-generator
        ├── api
        ├── docs
        ├── gradle
        └── src

ソースコードの移動

生成されたファイルを適切な場所にコピーします。手動でのコピーも可能ですが、ここでは Gradle タスクを利用して自動でのコピーを行う設定を紹介します。

tasks.register('copyOpenApiClientSrc', Copy) {
    from 'tmp/openapis/sample-api/src'
    into 'src'
}

tasks.named('openApiGenerate').configure {
    finalizedBy 'copyOpenApiClientSrc'
}

必要なライブラリの追加

公式のサンプルやビルド時のエラーメッセージを参考に、必要なライブラリを追加します。

私のパターンの場合には以下のライブラリを追加しました。

implementation 'jakarta.annotation:jakarta.annotation-api:2.1.+'
implementation 'org.openapitools:jackson-databind-nullable:0.2.+'

実装

出力結果のdocsディレクトリには、クライアントライブラリの使用方法が記載されています。これを基に実装を進めます。