Springdoc-openapiで始めるAPI仕様書の自動生成 #PERSOL CAREER Advent Calendar2025

はじめに
Springdoc-openapi とは
前提と注意
Springdoc-openapi の活用事例
OpenAPI として機能させるために必要なこと
バージョンに対応したアノテーションの形を理解する
まとめ

はじめに

アドベントカレンダー 21 日目の記事です。

こんにちは。 doda サイト開発でエンジニアをしている桐谷です。新卒でパーソルキャリアに入社後、 doda サイトのエンハンス開発に１年間携わり、現在はマイクロサービスチームで doda の求人領域の開発をしています。

今回は、私がマイクロサービスチームで初めて取り組んだタスクである Springdoc-openapi をはじめての方でも理解ができるように説明します。

Springdoc-openapi とは

Springdoc-openapi は Spring Boot のライブラリです。クラス内のアノテーションをもとにAPIの仕様書を自動生成します。開発者ごとに異なる仕様書が出来上がる心配もないため、開発者間の仕様の認識齟齬を防ぐことができます。

Spring は SpringFramework、doc は documentation の略です。 dog ではありません。openapi(OpenAPI) は API の仕様を JSON や YAML 形式で記述する標準フォーマットです。 OpenAI と言葉が似ていますが、 ChatGPT は作れません。

公式より OpenAPI のサンプル(JSON 形式)

https://demos.springdoc.org/demo-spring-boot-3-webmvc/v3/api-docs/users

前提と注意

Springdoc-openapi はライブラリなので定期的にバージョンが更新されます。

今回説明させていただくのは OpenAPI3.0, Springdoc-openapi v2.8.6 の情報です。

Springdoc-openapi の活用事例

1. Swagger UI

Swagger UI というブラウザ上で API のドキュメントを確認できるツールと連携できます。 API の概要が構造的に記されているため、はじめての方でも見やすいです。

公式より Swagger UI のサンプル

https://demos.springdoc.org/demo-spring-boot-3-webmvc/swagger-ui/index.html#/

2. Aspida との連携

Aspida については、フロントエンドを TypeScript、バックエンドを Spring Boot で実装する前提で説明をさせていただきます。

Aspida とは TypeScript から API と通信する際のパスやレスポンスの定義を型チェックも含めて自動生成してくれるという TypeScript のライブラリです。自動生成させるためには型定義ファイルを作成する必要があります。

型定義ファイルの例

GET：/v1/users/?limit={number}, POST：/v1/users

import type { DefineMethods } from "aspida";

type User = {
  id: number;
  name: string;
};

export type Methods = DefineMethods<{
  get: {
    query?: {
      limit: number;
    };

    resBody: User[];
  };

  post: {
    reqBody: {
      name: string;
    };

    resBody: User;
    /**
     * reqHeaders(?): ...
     * reqFormat: ...
     * status: ...
     * resHeaders(?): ...
     * polymorph: [...]
     */
  };
}>;

Aspida の設定方法について詳しくは公式ドキュメントに記載されています。

github.com

新規 API の呼び出しの度に上記のようなコードを書くことは手間が増えます。型定義を間違えてしまうリスクもあります。

そこで Aspida の型定義ファイルに Springdoc-openapi で Spring Boot の API 実装をもとに生成された OpenAPI を利用します。 TypeScript で上記のような型定義ファイルのコードを書かずに済みます。 API 通信においてリクエストする側の TypeScript とリクエストに対するレスポンスを返す側の Spring Boot の型定義に違いが生まれる心配もありません。

OpenAPI として機能させるために必要なこと

基本的には Springdoc-openapi のライブラリを SpringBoot の環境に導入し、アノテーションを指定するだけで OpenAPI として機能します。

ライブラリ導入手順はこちらに記載されています。

github.com

デフォルトでは、メディアタイプ : application/json, api-docs : openapi_3_0 となっております。

application.yaml で以下のように指定して必要に応じた変更をしてください。

springdoc:
  default-produces-media-type: application/json
  api-docs:
    version: openapi_3_0

公式が設定しているアノテーション

/**
 * Get id
 *
 * @return id
 */
@Schema(example = "10", description = "")


public Long getId() {
  return id;
}

public void setId(Long id) {
  this.id = id;
}


public User username(String username) {
  this.username = username;
  return this;
}

github.com

@Schema しか指定していません。とてもシンプルです。シンプルな API 構成であれば @Schema のみでも API ドキュメントとして十分に機能を発揮できます。 Swagger UI にも問題なく表示されます。

https://demos.springdoc.org/demo-spring-boot-3-webmvc/swagger-ui/index.html#/user/createUser

バージョンに対応したアノテーションの形を理解する

実際の開発現場ではネストされたリストやカスタムクラスを持つ値を扱うこともあるため、@Schema 以外を使用することもあります。例えば、@ArraySchema はリスト型の際に使用されることが一般的です。しかし、私は以下のように @ArraySchema の扱いに困りました。

・ @ArraySchema を指定しても OpenAPI が型をリストとして認識してくれない。

・カスタムクラスのリストは @ArraySchema でどのように扱えばよいのか。

・ @ArraySchema で定義した title がドキュメントに表記されない。

etc...

これらが発生する原因は、バージョンに対応したアノテーションの設定方法を理解できていないからです。 Springdoc-openapi は定期的なバージョン更新によってアノテーションの設定方法が変わることもあります。そのため、バージョン更新後にアノテーションの形を変えなければならないことがあります。その際は公式ドキュメントを参考に調査をする必要があります。

OpenAPI3.0 v2.8.6 の場合は以下のような結論で @ArraySchema の問題を解決できました。

// リスト型(List<String>)
@Schema(title = "ユーザー", example = "user1")

// カスタムクラスのリスト型(List<UserCode>)
@Schema(title = "ユーザー情報", example = "userInfo1")
@ArraySchema(schema = @Schema(implementation = UserCode.class))

Java の標準で用意されている参照型のリストは @Schema の指定のみでもライブラリがリスト型であると認識します。@ArraySchema の指定はカスタムクラスのリスト型のときにのみを使用します。 title や example は @Schema 内に書かなければライブラリが認識しません。

最新のバージョンは公式ページのタイトルで確認ができます。

springdoc.org

まとめ

今回は Springdoc-openapi の概要から扱い方までを簡単に説明させていただきました。紹介しきれなかった Springdoc-openapi に関連するアノテーションはまだまだあります。ライブラリを設定し、アノテーションをつけるだけで Swagger UI や Aspida とも連携できるため、開発生産性と安全性を大きく向上させることが期待できるライブラリです。この記事で Springdoc-openapi について１から知りたかった方や Springdoc-openapi をこれから導入しようと検討している方の参考となれば幸いです。