先生と生徒の会話形式で理解しよう

生徒

「先生、Micronautで作ったAPIの仕様書を自動で作る方法はありますか？」

先生

「MicronautではOpenAPIとSwaggerを使って、簡単にAPIドキュメントを生成することができます。」

生徒

「OpenAPIとSwaggerの違いって何ですか？」

先生

「OpenAPIはAPIの仕様を記述するための標準フォーマットで、Swaggerはその仕様を基にドキュメントを表示したり操作するツールです。」

生徒

「なるほど。実際にMicronautで設定する方法を教えてください。」

先生

「では、Gradle依存関係の追加から、コントローラに注釈を付けてドキュメントを生成する手順を見ていきましょう。」

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

MicronautでAPIドキュメントを生成するには、まずGradleプロジェクトに必要な依存関係を追加します。MicronautのOpenAPIモジュールを追加することで、自動的にAPI仕様書を生成できます。


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

依存関係を追加したら、application.ymlでOpenAPIの基本設定を行います。APIのタイトル、バージョン、説明などを設定しておくと、生成されるSwagger UIに反映されます。


micronaut:
  application:
    name: sample-api
  openapi:
    enabled: true
    title: "Sample API"
    version: "1.0.0"
    description: "Micronautで作成したサンプルAPI"

2. コントローラに注釈を追加してドキュメント化

Micronautのコントローラに@Controllerや@Get、@Postといった注釈を付けると、OpenAPIが自動でエンドポイント情報を収集します。さらに@Operationや@Parameterを使うと、より詳細な説明を付与できます。


import io.micronaut.http.annotation.*;
import io.swagger.v3.oas.annotations.*;

@Controller("/users")
public class UserController {

    @Get("/")
    @Operation(summary = "全ユーザーを取得するAPI", description = "ユーザー一覧をJSON形式で返します")
    public List<String> listUsers() {
        return List.of("Alice", "Bob", "Charlie");
    }
}

このように注釈を付けるだけで、Micronautはビルド時にOpenAPI仕様書を自動生成し、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仕様書を生成する

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

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

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ドキュメント生成のポイントと注意点

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

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

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

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