OpenAPI Generatorを使うと、OpenAPI YAMLで定義したAPI仕様から、JavaのモデルクラスやSpring Boot向けのAPIインターフェースを自動生成できます。

この記事では、GradleプロジェクトでOpenAPI Generatorを使い、Spring Boot 3向けのJavaコードを生成する基本手順を整理します。

この記事でやること

今回は、次の流れでOpenAPI Generatorを使います。

1. GradleにOpenAPI Generator Pluginを追加する
2. OpenAPI YAMLファイルを用意する
3. openApiGenerateタスクでJavaコードを生成する
4. 生成されたAPIインターフェースとモデルクラスを確認する
5. Spring Boot側で生成コードを使えるようにする

「OpenAPIの仕様を先に決めて、その仕様からコードを作る」流れにすると、API定義と実装のズレを減らしやすくなります。

OpenAPI Generatorとは

OpenAPI Generatorは、OpenAPI Specificationで書かれたAPI定義から、クライアントコード、サーバースタブ、モデル、ドキュメントなどを生成できるツールです。

Java/Spring Bootの場合は、spring generatorを使うことで、Spring向けのAPIインターフェースやモデルクラスを生成できます。

Gradleにプラグインを追加する

まず、build.gradleにOpenAPI GeneratorのGradleプラグインを追加します。

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.5.0'
    id 'io.spring.dependency-management' version '1.1.7'
    id 'org.openapi.generator' version '7.22.0'
}

OpenAPI Generatorのバージョンは更新されるため、実際に使うときはGradle Plugin Portalや公式ドキュメントで最新バージョンを確認してください。

依存関係を追加する

Spring Boot 3向けに生成する場合は、Jakarta EE系のimportが使われます。生成されるコードによって必要な依存関係は変わりますが、まずは次のような構成から始めると分かりやすいです。

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    implementation 'io.swagger.core.v3:swagger-annotations:2.2.30'
    implementation 'org.openapitools:jackson-databind-nullable:0.2.6'

    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

生成コードで使われるimportやアノテーションは、OpenAPI Generatorの設定やバージョンで変わることがあります。エラーが出た場合は、生成されたコードのimportを見て不足依存を確認するのが確実です。

OpenAPI YAMLを用意する

例として、src/main/resources/openapi.yamlに次のようなAPI定義を置きます。

openapi: 3.0.3
info:
  title: Customer API
  version: "1.0.0"
paths:
  /customers:
    get:
      summary: 顧客一覧を取得する
      operationId: getCustomers
      responses:
        "200":
          description: 顧客一覧
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Customer"
components:
  schemas:
    Customer:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        email:
          type: string

ポイントは、operationIdを付けておくことです。生成されるメソッド名に関わるため、実装側で読みやすい名前にしておくと後が楽になります。

openApiGenerateを設定する

次に、openApiGenerateタスクを設定します。

def generatedCodeDir = "$buildDir/generated"

openApiGenerate {
    generatorName = 'spring'
    inputSpec = "$projectDir/src/main/resources/openapi.yaml"
    outputDir = generatedCodeDir
    apiPackage = 'com.example.api'
    modelPackage = 'com.example.model'
    invokerPackage = 'com.example.invoker'
    configOptions = [
        interfaceOnly  : 'true',
        useSpringBoot3 : 'true',
        dateLibrary    : 'java8'
    ]
}

Spring Bootで自分のController実装を別に書きたい場合は、interfaceOnlyをtrueにして、APIインターフェースだけを生成する構成が扱いやすいです。

主な設定項目

よく使う設定を整理すると、次のようになります。

設定	意味
generatorName	どの種類のコードを生成するか。Spring Boot向けならspring。
inputSpec	入力に使うOpenAPI YAML/JSONファイル。
outputDir	生成コードの出力先。
apiPackage	APIインターフェースのパッケージ。
modelPackage	リクエスト/レスポンス用モデルのパッケージ。
interfaceOnly	APIインターフェース中心に生成する。実装クラスを自分で書きたい場合に便利。
useSpringBoot3	Spring Boot 3向けのコードを生成する。Jakarta EE系のimportを使う。

生成コードをソースセットに追加する

生成されたJavaコードをアプリ側から参照できるように、sourceSetsへ追加します。

sourceSets {
    main {
        java {
            srcDirs += "$generatedCodeDir/src/main/java"
        }
    }
}

compileJava.dependsOn tasks.named('openApiGenerate')

これで、compileJavaの前にopenApiGenerateが実行され、生成コードもコンパイル対象に含められます。

コード生成を実行する

設定できたら、次のコマンドでコードを生成します。

./gradlew openApiGenerate

成功すると、build/generated/src/main/java配下にAPIインターフェースやモデルクラスが生成されます。

生成されるコードのイメージ

上のYAMLをもとにすると、次のようなAPIインターフェースやモデルが生成されます。

package com.example.api;

import com.example.model.Customer;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;

import java.util.List;

@RequestMapping
public interface CustomersApi {

    @GetMapping("/customers")
    ResponseEntity<List<Customer>> getCustomers();
}

実際の生成内容は、OpenAPI Generatorのバージョンや設定によって少し変わります。大事なのは、生成されたインターフェースを見て、自分のController実装がどのメソッドを実装すればよいか確認することです。

Controllerで実装する

interfaceOnly構成の場合、生成されたインターフェースを実装するクラスを自分で作ります。

package com.example.controller;

import com.example.api.CustomersApi;
import com.example.model.Customer;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
public class CustomerController implements CustomersApi {

    @Override
    public ResponseEntity<List<Customer>> getCustomers() {
        Customer customer = new Customer();
        customer.setId(1L);
        customer.setName("yama");
        customer.setEmail("yama@example.com");

        return ResponseEntity.ok(List.of(customer));
    }
}

このように、APIの形はOpenAPI YAMLで管理し、実際の処理だけをControllerやServiceに書く流れにできます。

よくあるつまずき

javaxとjakartaが混ざる

Spring Boot 3ではJakarta EE系のimportを使います。古い設定や古いOpenAPI Generatorを使っていると、javax系のimportが出てコンパイルエラーになることがあります。

Spring Boot 3で使う場合は、useSpringBoot3 : 'true'を指定し、OpenAPI Generatorのバージョンも新しめにしておくのが無難です。

生成コードをGit管理するか迷う

生成コードをGitに含めるかどうかは、チーム方針によります。個人的には、OpenAPI YAMLを正として管理し、生成コードはビルド時に作り直せる状態にしておく方が扱いやすいです。

ただし、ビルド時間やCI環境、レビューしやすさを優先して生成コードも管理するチームもあります。どちらにするかは、プロジェクト内で統一しておくのが大事です。

operationIdを付けていない

operationIdがないと、生成されるメソッド名が分かりづらくなることがあります。実装クラスで扱いやすくするためにも、APIごとに意味のあるoperationIdを付けるのがおすすめです。

まとめ

OpenAPI Generatorを使うと、OpenAPI YAMLからJava/Spring Boot向けのAPIインターフェースやモデルクラスを自動生成できます。

特にSpring Boot 3で使う場合は、useSpringBoot3、interfaceOnly、sourceSetsへの追加、compileJava.dependsOnあたりを押さえておくと、実務でも使いやすい構成になります。

API仕様を先に整理し、その仕様からコードを生成することで、設計書と実装のズレを減らしやすくなります。

---

参考: OpenAPI Generator Plugins / OpenAPI Generator spring Generator / Gradle Plugin Portal: org.openapi.generator