Spring Boot + React + TypeScriptでOpenAPIから型を自動生成する方法

全体像

1. Spring BootにOpenAPIを導入
2. Swaggerへのアクセスを許可
3. 本番環境では無効化
4. Swagger UIを確認
5. フロントエンドで型生成
6. package.jsonにスクリプト追加
7. 型生成実行
8. 生成された型を利用

1. Spring BootにOpenAPIを導入する

pom.xml

<dependencies>
    <!-- ... -->
    <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.6.0</version>
    </dependency>

2. Swaggerへのアクセスを許可する

Spring Securityを利用している場合はSwagger関連のURLを許可します。

SecurityConfig.java

http
  // ...
  .authorizeHttpRequests(auth -> auth
    .requestMatchers(
      // ...
      "/v3/api-docs",
      "/v3/api-docs/**",
      "/swagger-ui/**",
      "/swagger-ui.html"
    ).permitAll()
    .anyRequest().authenticated()

3. 本番環境では無効化する

Swaggerは開発時のみ利用できれば十分です。

まずデフォルトでは無効にします。

application.yaml

springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

開発環境のみ有効化

application-dev.yaml

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true

4. Swagger UIを確認する

アプリ起動後、
http://localhost:8080/swagger-ui/index.html
へアクセスします。
Controllerから生成されたAPI一覧が表示されます。
ここでOpenAPI定義も/v3/api-docsから取得できます。

5. フロントエンドで型生成する

ライブラリ追加

npm install -D openapi-typescript

6. package.jsonにスクリプト追加

package.json

  "scripts": {
    // ...
    "gen:api-types": "openapi-typescript http://host.docker.internal:8080/v3/api-docs -o src/shared/api/schema.d.ts"
  },

※ http://host.docker.internal:8080 の部分は、自身のバックエンドサーバーのURLに置き換えてください。

7. 型生成実行

npm run gen:api-types

src/shared/api/schema.d.ts が生成されます。
このファイルは自動生成されるため、直接編集しません。

8. 生成された型を利用する

例えばOpenAPI定義に

UserResponse: {
  id: number;
  name?: string;
};

が含まれている場合、

import { components } from "@/shared/api/schema";

type User =
  components["schemas"]["UserResponse"];

のように利用できます。
API仕様を変更した場合は、型を再生成します。

npm run gen:api-types

補足: レスポンス型の必須項目

Javaの型だけでは、レスポンスJSONに各キーが必ず含まれるかどうかをOpenAPIが判断できない場合があります。

その場合、生成されたTypeScript型には ? が付きます。

レスポンスJSONに必ず含める項目には、レスポンスDTOで@Schema(requiredMode = Schema.RequiredMode.REQUIRED) を付けます

import io.swagger.v3.oas.annotations.media.Schema;

public record UserResponse(
  @Schema(requiredMode = Schema.RequiredMode.REQUIRED)
  Long id,

  String name
) {}

型を再生成すると、必須項目から?が外れます

id: number,
name?: string

@Schema(requiredMode = Schema.RequiredMode.REQUIRED) はOpenAPI上の契約を明示する設定です。
DB制約の変更や、実行時のnullチェックを行うものではありません。

まとめ

OpenAPIを利用すると、API仕様書と型定義を同じソースから管理できるようになります。
フロントエンドとバックエンド間の型ズレを防ぎながら開発を進められます。