MicronautのAPIドキュメント生成方法！OpenAPI/Swagger連携の基礎

1. MicronautでOpenAPI/Swaggerを利用する準備

1. MicronautでOpenAPI/Swaggerを利用する準備

MicronautでAPIドキュメントを自動生成するためには、まずプロジェクトの「設計図」となるGradleの設定ファイル（build.gradle）に、専用のライブラリ（依存関係）を追加する必要があります。

プログラミングが初めての方へ：「依存関係（dependencies）」とは、アプリを作るために必要な「道具箱」を外部から持ってくる設定のことです。ここでは、APIの仕様書を自動で作ってくれる「OpenAPI」という道具を導入します。

dependencies {
    // OpenAPIの機能を利用するためのライブラリ
    implementation("io.micronaut.openapi:micronaut-openapi")
    // コンパイル（プログラムの変換）時にドキュメントを自動生成するプロセッサ
    annotationProcessor("io.micronaut.openapi:micronaut-openapi")
}

次に、アプリの基本情報を定義するapplication.ymlという設定ファイルを編集します。ここに記述した内容が、そのままWeb上で見る仕様書のタイトルや説明文として表示されます。

例えば、あなたが「名簿管理システム」を作っているなら、タイトルを「ユーザー管理API」とすることで、誰が見ても何のためのプログラムかが一目でわかるようになります。

micronaut:
  application:
    name: sample-api
  openapi:
    # OpenAPI機能を有効にする設定
    enabled: true
    # ブラウザで表示される仕様書のタイトル
    title: "はじめてのSample API"
    # アプリのバージョン管理（最初は1.0.0でOK）
    version: "1.0.0"
    # このAPIが何をするものかという簡単な説明
    description: "Micronautで作成した、初心者向けの学習用サンプルAPIです。"

これで、APIドキュメントを生成するための「土台」が完成しました。これらの設定を行うだけで、複雑なコードを自分で書かなくても、Micronautが裏側でドキュメントの生成準備を整えてくれます。

2. コントローラに注釈（アノテーション）を追加してドキュメント化

2. コントローラに注釈（アノテーション）を追加してドキュメント化

MicronautでAPIを作成する際、ソースコードに「これはWebの入り口ですよ」という印を付けるだけで、自動的に説明書（API仕様書）を作成できます。この印のことをJavaでは注釈（アノテーション）と呼びます。

例えば、@Controllerはクラス全体がWebの受付窓口であることを示し、@Getや@Postは「どのような操作（取得や保存）を行うか」を指定する役割を持っています。これらに加えて、OpenAPI用の注釈を使うことで、プログラミングに詳しくない人が見ても一目で使い方がわかるドキュメントが出来上がります。

import io.micronaut.http.annotation.*;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import java.util.List;

@Controller("/users") // 「/users」というURLでアクセスを受け付ける設定
public class UserController {

    @Get("/") // データを取得する（GET）ための窓口
    @Operation(
        summary = "登録されている全ユーザーの名前を取得",
        description = "システムに登録されているユーザーを一覧形式で取得します。引数は不要です。"
    )
    @ApiResponse(responseCode = "200", description = "正常にリストを取得できました")
    public List<String> listUsers() {
        // 本来はデータベースから取得しますが、ここでは簡単な例として名前を返します
        return List.of("アリス", "ボブ", "チャーリー");
    }
}

上記のコードでは、summary（要約）やdescription（詳細説明）を記述しています。これにより、ビルド（プログラムの構築）を行うだけで、Micronautが背後で「Swagger UI」という視覚的なツールと連携し、ブラウザ上でボタンを押すだけでAPIをテストできる環境まで整えてくれるのです。

難しい設定ファイルを手書きする必要はなく、Javaのコード内に「メモ」を残す感覚で進められるのが、MicronautとOpenAPIを組み合わせる最大のメリットです。

3. Swagger UIの有効化

3. Swagger UIの有効化

Micronautではmicronaut-openapiとmicronaut-swagger-uiを組み合わせることで、ブラウザ上でAPIを確認できるSwagger UIを簡単に利用できます。

dependencies {
    implementation("io.micronaut.openapi:micronaut-openapi")
    implementation("io.micronaut.openapi:micronaut-swagger-ui")
}

アプリケーションを起動すると、デフォルトで/swagger-uiにアクセスすることで、APIドキュメントを確認可能です。これにより、フロントエンド開発者やテスターが簡単にAPIを理解でき、開発効率が向上します。

4. ビルド時にOpenAPI仕様書を生成する

4. ビルド時にOpenAPI仕様書を生成する

Micronautではビルド時にOpenAPI仕様書を自動生成します。Gradleを利用している場合、./gradlew assembleや./gradlew buildを実行すると、build/classes/java/main/META-INF/swagger配下にopenapi.jsonが生成されます。

このファイルをCI/CDで利用したり、Swagger UIに読み込ませることで、常に最新のAPIドキュメントを提供できます。

5. サンプルプロジェクトで確認する

5. サンプルプロジェクトで確認する

簡単なサンプルプロジェクトを作成して、OpenAPIとSwagger UIを試してみましょう。

import io.micronaut.runtime.Micronaut;

public class Application {
    public static void main(String[] args) {
        Micronaut.run(Application.class, args);
        System.out.println("Micronaut APIサーバーが起動しました。Swagger UIで確認可能です。");
    }
}

Micronaut APIサーバーが起動しました。Swagger UIで確認可能です。

上記のサンプルを起動し、http://localhost:8080/swagger-uiにアクセスすると、ユーザー取得APIの仕様が表示されます。これにより、開発中のAPIを簡単に確認したり、フロントエンドやテストチームに共有できます。

6. APIドキュメント生成のポイントと注意点

6. APIドキュメント生成のポイントと注意点

MicronautでOpenAPI/Swaggerを活用する際のポイントは以下の通りです。

• コントローラやメソッドに適切な注釈を付けることで、自動生成のドキュメントの精度が向上します。
• APIパラメータやレスポンスに@Parameterや@ApiResponseを使用して詳細を記述すると、Swagger UIに反映されます。
• ビルドキャッシュやインクリメンタルビルドを利用して、OpenAPI生成時間を短縮できます。
• Swagger UIは開発環境向けに利用し、本番環境では必要に応じて制御することが推奨されます。

これらを理解しておくと、MicronautプロジェクトのAPI仕様書を効率的に作成でき、チーム開発やドキュメント管理がスムーズになります。