# MicronautでのAPIドキュメント生成（OpenAPI/Swagger）

## 1. 目次

1. はじめに

2. Micronautとは

   1. Micronautの概要

   2. Micronautが選ばれる理由

3. OpenAPI/Swaggerとは

   1. OpenAPIの歴史と目的

   2. Swaggerとの関係

4. MicronautでのOpenAPI/Swagger統合

   1. 必要な依存関係の設定

   2. アノテーションの使用法

   3. ドキュメント生成のプロセス

5. カスタマイズと拡張

   1. OpenAPI仕様のカスタマイズ

   2. UIのカスタマイズ

6. 実践例

   1. 簡単なCRUD APIの作成

   2. ドキュメント生成の実演

7. よくある質問とトラブルシューティング

8. まとめ

### 1. はじめに

APIが増加する中で、開発者がAPIの機能や使い方を理解しやすくするためのドキュメント生成は急務です。MicronautはJavaおよびKotlinアプリケーション用の最新フレームワークで、アプリケーションの起動時にすべてが遅延ロードされるのではなく、コンパイル時にさらに多くの作業を行います。そのため非常に効率的です。このドキュメントでは、MicronautでOpenAPIを使用してAPIドキュメントを生成する方法を詳しく解説します。

### 2. Micronautとは

#### 2-1. Micronautの概要

Micronautは、モダンなマイクロサービス志向で設計されたJavaフレームワークです。

- **主な特徴**:

  - コンパイル時の依存性注入

  - 軽量で起動時間が迅速

  - ネイティブイメージのサポート

#### 2-2. Micronautが選ばれる理由

Micronautは、Amazon Lambdaのようなクラウド環境にも最適化されています。起動時間が短く、メモリ消費も少ないため、リソースコストを削減できます。

### 3. OpenAPI/Swaggerとは

#### 3-1. OpenAPIの歴史と目的

OpenAPIは、APIを記述するための標準フォーマットを提供し、開発者がAPIを効率的に作成するのに役立ちます。

- **バージョンの進化**:

  - 初期はSwaggerとして知られ、その後Linux Foundationのもとで成長しました。

#### 3-2. Swaggerとの関係

Swaggerは、OpenAPI仕様が策定される前の名前であり、現在もUIツールとして使用されることが多いです。

### 4. MicronautでのOpenAPI/Swagger統合

#### 4-1. 必要な依存関係の設定

MicronautでOpenAPIを統合するには、以下の依存関係を`build.gradle`または`pom.xml`に追加します。

```groovy

dependencies {

    implementation("io.micronaut.openapi:micronaut-openapi")

    implementation("io.swagger.core.v3:swagger-annotations")

}

```

#### 4-2. アノテーションの使用法

`@Controller`や`@Get`といったアノテーションを使用して、エンドポイントを明確にします。

```java

import io.micronaut.http.annotation.*;

@Controller("/books")

public class BookController {

    @Get("/")

    public List<String> listBooks() {

        return Arrays.asList("The Hobbit", "1984");

    }

}

```

#### 4-3. ドキュメント生成のプロセス

プロジェクトをビルドする際、Micronautは自動的にOpenAPIドキュメントを生成します。このドキュメントは通常、`build/classes/java/main/META-INF/swagger`に出力されます。

### 5. カスタマイズと拡張

#### 5-1. OpenAPI仕様のカスタマイズ

プロジェクトのルートに`src/main/resources/openapi.yml`を追加して、独自のOpenAPI仕様を上書きできます。

#### 5-2. UIのカスタマイズ

Swagger UIをMicronautプロジェクトに組み込み、API仕様を視覚的にチェックできます。このUIは、HTML/CSSを使用してカスタマイズ可能です。

### 6. 実践例

#### 6-1. 簡単なCRUD APIの作成

例として、簡単なCRUDアプリケーションを構築します。このアプリケーションでは、リソースの作成、取得、更新、削除ができるAPIを提供します。

```java

import io.micronaut.http.annotation.*;

@Controller("/books")

public class BookController {

    private final Map<Long, String> books = new HashMap<>();

    @Post("/")

    public HttpResponse<Long> addBook(@Body String name) {

        long id = books.size() + 1;

        books.put(id, name);

        return HttpResponse.created(id);

    }

    @Get("/{id}")

    public Optional<String> getBook(Long id) {

        return Optional.ofNullable(books.get(id));

    }

    @Put("/{id}")

    public HttpResponse updateBook(Long id, @Body String name) {

        if (books.containsKey(id)) {

            books.put(id, name);

            return HttpResponse.ok();

        }

        return HttpResponse.notFound();

    }

    @Delete("/{id}")

    public HttpResponse deleteBook(Long id) {

        if (books.containsKey(id)) {

            books.remove(id);

            return HttpResponse.ok();

        }

        return HttpResponse.notFound();

    }

}

```

#### 6-2. ドキュメント生成の実演

ビルド後、生成されたOpenAPIドキュメントをSwagger UIで確認し、すべてのエンドポイントが正しく記述されていることを確認します。

### 7. よくある質問とトラブルシューティング

- **依存関係が見つからない場合**:

  MavenやGradleのキャッシュをクリアし、再ビルドを行います。

- **Swagger UIが動作しない場合**:

  デプロイ環境が開発モードであり、`micronaut.openapi.enabled`が`true`であることを確認してください。

### 8. まとめ

MicronautによるAPI開発は、効率的で最新のアーキテクチャを活用したものです。OpenAPI/Swaggerと統合することで、ドキュメント生成も簡単に行え、開発者は他のプロジェクトでもそのスキルを活用できます。APIの拡張性を持ち、高品質なAPIの提供を可能にするMicronautは、今後の可能性を広げるフレームワークとして有望です。

MicronautでのAPIドキュメント生成（OpenAPI/Swagger）

1. 目次

続きを読むには単価診断を受けてください（30秒）