MENU
  1. ホーム
  2. Java
  3. Spring REST Docsを使ったAPIドキュメントの自動生成手順を徹底解説

Spring REST Docsを使ったAPIドキュメントの自動生成手順を徹底解説

Java

Spring REST Docsを使用したAPIドキュメンテーションの自動生成は、開発者にとって非常に便利な手法です。APIの実装とドキュメントが常に同期されていることで、ドキュメントの更新漏れや不整合を防ぎ、ユーザーに信頼性の高いドキュメントを提供できます。さらに、手動でのドキュメント作成に比べて、Spring REST Docsは自動化されたプロセスを通じて作業効率を大幅に向上させます。本記事では、Spring REST Docsを用いてAPIドキュメンテーションを自動的に生成する手順や実践的な応用方法を紹介し、効率的な開発フローを構築する方法を詳しく解説します。

目次
  1. Spring REST Docsとは
    1. ドキュメントの自動生成
    2. RESTful API開発における利点
  2. 必要な環境設定
    1. Mavenプロジェクトの設定
    2. Gradleプロジェクトの設定
    3. その他の必要な設定
  3. サンプルプロジェクトの作成
    1. Spring Bootプロジェクトの作成
    2. シンプルなREST APIの実装
    3. テストの追加
    4. プロジェクトのビルドと実行
  4. REST APIのテスト設計
    1. MockMvcのセットアップ
    2. 基本的なテストケースの作成
    3. 詳細なテストの追加
    4. テスト結果の確認とドキュメント生成
  5. APIエンドポイントのドキュメント化
    1. ドキュメント生成の流れ
    2. スニペットの内容例
    3. 生成されたスニペットの統合
    4. エラーハンドリングとドキュメント化
    5. ドキュメントの構造
  6. スニペットのカスタマイズ
    1. カスタムフィールドの追加
    2. プレプロセッサの使用
    3. テンプレートのカスタマイズ
    4. リクエストとレスポンスの例のカスタマイズ
    5. 組織に合わせたドキュメント形式の作成
  7. 静的HTMLドキュメントの生成
    1. Asciidoctorを使ったドキュメント生成
    2. ドキュメントの構造
    3. HTMLドキュメントの生成
    4. HTMLドキュメントのカスタマイズ
    5. 生成されたドキュメントの確認と活用
  8. CI/CDパイプラインへの統合
    1. CI/CDパイプラインの基本構造
    2. Jenkinsへの統合例
    3. GitLab CIへの統合例
    4. CI/CDでの成果物の公開
    5. CI/CD統合の利点
  9. 応用例：APIバージョン管理
    1. APIバージョニングの実装
    2. バージョンごとのテストコードの実装
    3. ドキュメントの統合と生成
    4. APIバージョニングの運用
    5. APIバージョニングの利点
  10. ドキュメントの公開
    1. 公開方法の選択
    2. GitHub Pagesを使用した公開例
    3. AWS S3を使用した公開例
    4. 公開時のセキュリティ対策
    5. 定期的なドキュメント更新の自動化
    6. 公開ドキュメントの管理
  11. まとめ

Spring REST Docsとは

Spring REST Docsは、Springフレームワークを使って開発されたREST APIのドキュメンテーションを自動的に生成するためのツールです。主に、APIのテストを行う際に、テストコードからドキュメントを生成することで、APIの実装とドキュメントを常に最新の状態に保つことができます。

ドキュメントの自動生成

Spring REST Docsは、JUnitやSpring Testを用いて実施するAPIテストの結果を元に、APIエンドポイントの仕様を自動的にドキュメント化します。このプロセスでは、テストケースで送信したリクエストやレスポンス、ヘッダー情報、HTTPメソッド、ステータスコードなどが詳細に記録され、ドキュメントが生成されます。

RESTful API開発における利点

Spring REST Docsを使用することで、手動によるドキュメントの作成や更新を省くことができ、特にAPIの頻繁な更新や変更があるプロジェクトでは、開発者の負担を軽減します。また、テストに基づいたドキュメント生成により、API仕様と実装の乖離を防ぎ、信頼性の高いドキュメントが得られるため、利用者にとっても正確な情報が提供されます。

必要な環境設定

Spring REST Docsを使用するためには、プロジェクトに適切な依存ライブラリを追加し、設定を行う必要があります。ここでは、MavenやGradleを使用してSpring REST Docsの環境を構築する方法について説明します。

Mavenプロジェクトの設定

Mavenを使用している場合、pom.xmlにSpring REST Docsの依存関係を追加します。以下の依存ライブラリを記述することで、APIドキュメントを自動生成できる環境が整います。

<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
    <version>2.0.6.RELEASE</version>
    <scope>test</scope>
</dependency>

これは、Spring MockMvcを使用してテストを行う場合の依存設定です。他にも、WebTestClientを使用する場合には、spring-restdocs-webtestclientを追加します。

Gradleプロジェクトの設定

Gradleを使用している場合、build.gradleに以下の依存関係を追加します。

dependencies {
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc:2.0.6.RELEASE'
}

これにより、テスト環境でSpring REST Docsを利用できるようになります。

その他の必要な設定

Spring REST Docsでは、APIテスト結果を基にドキュメントが生成されるため、テスト実行時にドキュメントを出力するディレクトリを設定する必要があります。通常、build.gradleまたはpom.xmlに適切な設定を追加して、生成されるスニペット（APIドキュメントの断片）が保存される場所を指定します。

test {
    outputs.dir snippetsDir
}

この設定により、テスト実行後にAPIエンドポイントの情報が自動的にスニペットとして生成され、後にHTMLドキュメントとしてまとめられます。

サンプルプロジェクトの作成

Spring REST Docsを活用するためには、まずテストベースのドキュメント生成に対応したREST APIプロジェクトを準備する必要があります。ここでは、シンプルなSpring Bootアプリケーションを作成し、APIドキュメントを自動生成するための基本的な設定方法を解説します。

Spring Bootプロジェクトの作成

まず、Spring Initializr（https://start.spring.io/）を使用して新しいSpring Bootプロジェクトを作成します。以下のように設定してください。

  • Project: Maven Project
  • Language: Java
  • Spring Boot Version: 2.6.x 以上
  • Dependencies:
  • Spring Web
  • Spring Boot DevTools
  • Lombok（任意）
  • Spring REST Docs

プロジェクトを生成したら、ダウンロードしてIDEで開きます。

シンプルなREST APIの実装

次に、簡単なREST APIを作成します。ここでは、例として/api/greetingsエンドポイントを作成し、”Hello, World!”というメッセージを返すAPIを実装します。

@RestController
@RequestMapping("/api")
public class GreetingController {

    @GetMapping("/greetings")
    public ResponseEntity<String> getGreeting() {
        return ResponseEntity.ok("Hello, World!");
    }
}

このコードにより、/api/greetingsエンドポイントにGETリクエストを送ると、”Hello, World!”というレスポンスを取得できるシンプルなAPIが実装されます。

テストの追加

Spring REST Docsでは、テストコードを使ってドキュメントを生成します。まず、src/test/javaディレクトリにテストクラスを作成し、MockMvcを使ってエンドポイントをテストします。

@WebMvcTest(GreetingController.class)
public class GreetingControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void shouldReturnGreeting() throws Exception {
        this.mockMvc.perform(get("/api/greetings"))
            .andExpect(status().isOk())
            .andExpect(content().string("Hello, World!"))
            .andDo(document("greetings"));
    }
}

このテストでは、/api/greetingsエンドポイントのレスポンスが期待通りであることを確認し、その後、Spring REST Docsのdocument()メソッドを使ってAPIドキュメントを生成しています。

プロジェクトのビルドと実行

テストコードを追加した後、MavenやGradleを使ってテストを実行します。テストが成功すると、Spring REST Docsによってドキュメントのスニペットが生成されます。これらのスニペットは後ほど静的なHTMLドキュメントとしてまとめられます。

このようにして、シンプルなSpring BootプロジェクトにREST APIとテストを実装し、APIドキュメントを自動生成する準備が整います。

REST APIのテスト設計

Spring REST Docsを使用してAPIドキュメントを自動生成するためには、APIエンドポイントに対するテストを設計し、その結果を基にドキュメントを生成することが重要です。ここでは、MockMvcを使用したAPIテストの設計と実装方法を解説します。

MockMvcのセットアップ

Spring REST Docsでは、APIリクエストとレスポンスをシミュレーションするために、MockMvcを使用してテストを行います。MockMvcは、Spring MVCアプリケーションのコントローラー層をWebサーバーを起動せずにテストするためのツールです。

テストクラスでMockMvcをセットアップし、テストの準備を行います。

@WebMvcTest(GreetingController.class)
@AutoConfigureRestDocs(outputDir = "target/snippets")
public class GreetingControllerTest {

    @Autowired
    private MockMvc mockMvc;

    // その他のテストコード
}

ここで@AutoConfigureRestDocsアノテーションを使用し、ドキュメントのスニペットを生成するディレクトリを指定します。この設定により、テストの実行時にスニペットが自動生成されます。

基本的なテストケースの作成

実際にエンドポイントの動作をテストするための基本的なテストケースを作成します。以下は、/api/greetingsエンドポイントの動作を検証し、その結果をドキュメント化するテストです。

@Test
public void shouldReturnGreeting() throws Exception {
    this.mockMvc.perform(get("/api/greetings"))
        .andExpect(status().isOk())
        .andExpect(content().string("Hello, World!"))
        .andDo(document("greetings", 
            preprocessRequest(prettyPrint()), 
            preprocessResponse(prettyPrint())));
}

このテストケースでは、エンドポイントにGETリクエストを送信し、レスポンスが"Hello, World!"であることを確認しています。また、document()メソッドを使用して、テスト結果を基にAPIドキュメントを生成しています。preprocessRequest()およびpreprocessResponse()は、リクエストおよびレスポンスの内容を整形して出力するためのオプションで、ドキュメントが読みやすくなります。

詳細なテストの追加

より詳細なドキュメントを生成するためには、ヘッダー情報やパラメータのテストも追加できます。例えば、以下のように、クエリパラメータを含むリクエストのテストとドキュメント生成を行います。

@Test
public void shouldReturnGreetingWithParams() throws Exception {
    this.mockMvc.perform(get("/api/greetings")
        .param("name", "John"))
        .andExpect(status().isOk())
        .andExpect(content().string("Hello, John!"))
        .andDo(document("greeting-with-params", 
            requestParameters(
                parameterWithName("name").description("挨拶する相手の名前")
            ),
            preprocessRequest(prettyPrint()), 
            preprocessResponse(prettyPrint())));
}

このテストでは、nameというクエリパラメータを付けてAPIを呼び出し、その結果を検証しています。さらに、requestParameters()を使って、リクエストで使用されるパラメータについての説明をドキュメントに追加しています。

テスト結果の確認とドキュメント生成

テストを実行すると、指定されたディレクトリにスニペットが生成されます。このスニペットは、リクエストやレスポンスの詳細、パラメータ情報などが含まれたAPIドキュメントの断片です。これらのスニペットを後でまとめて、完全なドキュメントとして生成します。

このようにして、テストベースでAPIの動作を検証しながら、同時に自動的にドキュメントを生成するプロセスを設計することができます。

APIエンドポイントのドキュメント化

Spring REST Docsを使用すると、テストコードを基にしてAPIエンドポイントの詳細なドキュメントを自動生成することができます。ここでは、生成されたスニペットを活用して、どのようにAPIエンドポイントのドキュメントを作成するかを説明します。

ドキュメント生成の流れ

APIエンドポイントのドキュメント化は、テスト実行時に自動的に行われます。テストコードでdocument()メソッドを呼び出すことで、リクエストやレスポンス、ヘッダー、パラメータ情報がスニペットとして出力されます。これらのスニペットを集約し、最終的なAPIドキュメントに統合します。

テスト実行後、スニペットは指定されたディレクトリ（通常はtarget/snippets）に生成されます。例えば、/api/greetingsエンドポイントのテストを実行した場合、以下のようなスニペットが生成されます。

  • greetings-http-request.adoc（HTTPリクエストの内容）
  • greetings-http-response.adoc（HTTPレスポンスの内容）
  • greetings-parameters.adoc（パラメータの説明）

スニペットの内容例

テスト実行後に生成されたスニペットは、具体的なAPIの仕様を記述したAdoc形式のファイルです。例えば、以下のようなリクエストやレスポンスのスニペットが生成されます。

リクエストスニペット（greetings-http-request.adoc）:

==== Example request:
GET /api/greetings HTTP/1.1
Host: localhost:8080

レスポンススニペット（greetings-http-response.adoc）:

==== Example response:
HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8

Hello, World!

これらのスニペットは、APIドキュメントに組み込まれるための断片となり、APIのリクエストやレスポンスの例として提供されます。

生成されたスニペットの統合

Spring REST Docsは、生成されたスニペットをMarkdownやAsciidoctor形式のファイルに統合し、最終的なAPIドキュメントとして整えることができます。例えば、Asciidoctorを使用して以下のような内容でドキュメントを統合します。

= Greetings API Documentation

== /api/greetings
=== HTTP Request
include::{snippets}/greetings-http-request.adoc[]

=== HTTP Response
include::{snippets}/greetings-http-response.adoc[]

このようにincludeディレクティブを使うことで、生成されたスニペットをAPIドキュメントに埋め込みます。これにより、リクエストとレスポンスの例が一貫して表示されるようになります。

エラーハンドリングとドキュメント化

APIでは正常系のレスポンスだけでなく、エラーレスポンスもドキュメント化することが重要です。例えば、パラメータの不備や認証エラーが発生した場合のレスポンスをテストし、それをドキュメントに含めることができます。

@Test
public void shouldReturnBadRequestForMissingParam() throws Exception {
    this.mockMvc.perform(get("/api/greetings"))
        .andExpect(status().isBadRequest())
        .andDo(document("greetings-error",
            responseFields(
                fieldWithPath("error").description("エラーメッセージ"),
                fieldWithPath("status").description("HTTPステータスコード"))));
}

このように、エラーレスポンスのテストとそのドキュメント化も同時に行うことで、利用者に対して正確なエラーハンドリング情報を提供できます。

ドキュメントの構造

最終的なAPIドキュメントは、複数のスニペットを組み合わせて作成します。例えば、各APIエンドポイントごとに以下のような情報を含むドキュメントを生成できます。

  • エンドポイントのURL
  • HTTPメソッド
  • リクエストのヘッダーやパラメータ
  • レスポンス例
  • エラーレスポンス

こうして、APIの全体像を詳細に把握できるドキュメントが自動生成され、開発者や利用者にとって非常に役立つ情報が提供されます。

スニペットのカスタマイズ

Spring REST Docsでは、自動生成されたスニペットをプロジェクトやAPI仕様に合わせてカスタマイズすることができます。これにより、APIの説明がより詳細で分かりやすくなり、利用者に対して正確な情報を提供することが可能です。ここでは、スニペットのカスタマイズ方法について説明します。

カスタムフィールドの追加

生成されるスニペットに、APIの詳細な説明を追加することができます。例えば、リクエストやレスポンスのフィールドについて、詳細な説明や型情報を追加することが可能です。

@Test
public void shouldReturnGreetingWithCustomFields() throws Exception {
    this.mockMvc.perform(get("/api/greetings"))
        .andExpect(status().isOk())
        .andExpect(content().string("Hello, World!"))
        .andDo(document("greetings-custom", 
            responseFields(
                fieldWithPath("message").description("挨拶のメッセージ"),
                fieldWithPath("timestamp").description("レスポンス生成時刻").type("String"))));
}

このコードでは、レスポンスフィールドのmessageとtimestampにカスタム説明を追加しています。こうすることで、フィールドがどのような役割を持っているか、開発者やAPI利用者にとって理解しやすくなります。

プレプロセッサの使用

Spring REST Docsには、リクエストやレスポンスの内容を整形するための「プレプロセッサ」を利用する機能があります。これにより、読みやすいドキュメントを生成することができます。たとえば、JSON形式のレスポンスをインデントして出力するには、prettyPrint()メソッドを使います。

@Test
public void shouldDocumentWithPrettyPrint() throws Exception {
    this.mockMvc.perform(get("/api/greetings"))
        .andExpect(status().isOk())
        .andDo(document("greetings-pretty", 
            preprocessResponse(prettyPrint())));
}

この設定により、生成されたレスポンススニペットが整形され、視覚的に分かりやすいドキュメントが作成されます。

テンプレートのカスタマイズ

スニペットの見た目や構造をさらにカスタマイズしたい場合、Spring REST Docsではテンプレートを変更することができます。デフォルトでは、Asciidoctor形式でスニペットが生成されますが、このテンプレートを独自の形式にカスタマイズできます。

例えば、src/test/resources/org/springframework/restdocs/templatesディレクトリにカスタムテンプレートファイルを作成し、デフォルトのテンプレートを上書きします。これにより、APIドキュメントのレイアウトや内容を柔軟に変更できます。

リクエストとレスポンスの例のカスタマイズ

リクエストやレスポンスの例をカスタマイズすることで、利用者にとって特に重要な情報を強調することができます。たとえば、特定のパラメータを含むリクエスト例や、特定の条件下でのレスポンスをドキュメントに含めることで、実際のAPI使用に近い例を提示できます。

@Test
public void shouldDocumentCustomRequestResponse() throws Exception {
    this.mockMvc.perform(post("/api/greetings")
        .content("{\"name\":\"John\"}")
        .contentType(MediaType.APPLICATION_JSON))
        .andExpect(status().isOk())
        .andDo(document("custom-example", 
            requestFields(
                fieldWithPath("name").description("挨拶する相手の名前")),
            responseFields(
                fieldWithPath("message").description("挨拶のメッセージ"))));
}

このテストでは、リクエストとレスポンスの両方にカスタムフィールドを追加し、APIの仕様をより明確にしています。

組織に合わせたドキュメント形式の作成

企業やチームのドキュメント規格に合わせて、出力されるスニペットのフォーマットを統一することも重要です。スニペットはJSONやXML、Markdown形式にカスタマイズすることができ、必要に応じてテンプレートを調整することで、プロジェクト全体で一貫したドキュメントスタイルを維持できます。

このように、Spring REST Docsを使用することで、APIドキュメントを柔軟にカスタマイズし、実際の使用に即したドキュメントを生成することが可能です。

静的HTMLドキュメントの生成

Spring REST Docsでは、生成されたスニペットを元に、APIの静的なHTMLドキュメントを作成することができます。HTML形式のドキュメントは、プロジェクト内での共有や外部公開に適しており、読みやすく整ったAPI仕様書を提供します。ここでは、Asciidoctorを使用してスニペットをHTMLドキュメントに統合する方法を説明します。

Asciidoctorを使ったドキュメント生成

Spring REST DocsはAsciidoctorというツールを使用して、生成されたスニペットをまとめたドキュメントをHTML形式で生成します。まずは、プロジェクトにAsciidoctorのプラグインを設定し、HTMLドキュメントを自動生成する環境を整えます。

Mavenでの設定

Mavenプロジェクトの場合、pom.xmlに以下のようにAsciidoctorプラグインを追加します。

<build>
    <plugins>
        <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>2.1.0</version>
            <executions>
                <execution>
                    <goals>
                        <goal>process-asciidoc</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

このプラグインにより、process-asciidocフェーズでスニペットが含まれたHTMLドキュメントが自動的に生成されます。

Gradleでの設定

Gradleの場合、build.gradleに以下のプラグインを追加します。

plugins {
    id 'org.asciidoctor.convert' version '3.3.2'
}

asciidoctor {
    sources {
        include 'index.adoc'
    }
    dependsOn test
    inputs.dir snippetsDir
    doLast {
        copy {
            from outputDir
            into "${buildDir}/docs/asciidoc"
        }
    }
}

これにより、テスト実行後にAsciidoctorが動作し、生成されたスニペットを組み込んだHTMLドキュメントが生成されます。

ドキュメントの構造

次に、Asciidoctorを使って生成されるドキュメントの構造を定義します。通常、src/docs/asciidocフォルダにindex.adocファイルを作成し、スニペットを組み込むドキュメントのベースファイルを定義します。

以下は、index.adocファイルの例です。

= API Documentation

== Greetings API

=== GET /api/greetings
include::{snippets}/greetings-http-request.adoc[]
include::{snippets}/greetings-http-response.adoc[]

=== POST /api/greetings
include::{snippets}/custom-example-http-request.adoc[]
include::{snippets}/custom-example-http-response.adoc[]

この構造では、テスト実行時に生成されたスニペット（リクエストとレスポンスの例）が含まれ、APIドキュメントに挿入されます。

HTMLドキュメントの生成

設定が完了したら、MavenまたはGradleのビルドを実行します。Mavenの場合、以下のコマンドを使用します。

mvn clean install

Gradleの場合は、次のコマンドでビルドを実行します。

gradle build

ビルドが成功すると、build/docs/asciidoc（またはtarget/generated-docs）ディレクトリにHTML形式のAPIドキュメントが生成されます。このドキュメントは、ブラウザで開いて確認することができ、APIのリクエストやレスポンス、パラメータの説明などがすべて表示されます。

HTMLドキュメントのカスタマイズ

生成されるHTMLドキュメントは、Asciidoctorのテンプレートやテーマを使って見た目をカスタマイズすることが可能です。Asciidoctorの設定ファイルで、フォントや配色、レイアウトなどを変更できます。例えば、build.gradleやpom.xmlに以下の設定を追加することで、テーマを変更できます。

asciidoctor {
    attributes 'linkcss': true, 'stylesheet': 'custom.css'
}

このようにして、企業やプロジェクトのスタイルガイドに合ったドキュメントを提供することができます。

生成されたドキュメントの確認と活用

生成された静的なHTMLドキュメントは、社内で共有したり、API利用者に提供するために公開したりすることができます。また、ドキュメントが常に最新のAPI仕様に基づいて生成されるため、開発の進行に応じて自動的に更新され、信頼性の高いドキュメントを維持できます。

このように、Spring REST Docsを使用してスニペットを元に静的なHTMLドキュメントを自動生成することで、APIのドキュメント管理を効率化し、開発プロセス全体の生産性を向上させることができます。

CI/CDパイプラインへの統合

Spring REST DocsによるAPIドキュメント生成は、継続的インテグレーション（CI）および継続的デリバリー（CD）パイプラインに統合することで、テスト実行時に自動的に最新のドキュメントが生成され、デプロイメントプロセスが効率化されます。ここでは、CI/CDパイプラインにSpring REST Docsを組み込む方法について説明します。

CI/CDパイプラインの基本構造

CI/CDパイプラインにSpring REST Docsを統合するためには、まずパイプライン内でテストが自動的に実行されるように設定し、その後にAPIドキュメントが生成されるプロセスを構築します。一般的なパイプラインの流れは以下の通りです。

  1. ソースコードのプッシュまたはマージに応じてビルドをトリガー
  2. 自動テストを実行し、Spring REST Docsのスニペットを生成
  3. 生成されたスニペットを基にドキュメントを生成
  4. HTMLドキュメントを成果物として保存またはデプロイ

Jenkinsへの統合例

Jenkinsを使用している場合、Jenkinsfileで以下のようにパイプラインを設定することで、Spring REST DocsによるAPIドキュメント生成を自動化できます。

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'mvn clean install'
            }
        }
        stage('Test') {
            steps {
                sh 'mvn test'
            }
        }
        stage('Generate Docs') {
            steps {
                sh 'mvn asciidoctor:process-asciidoc'
            }
        }
    }
    post {
        always {
            archiveArtifacts artifacts: 'target/generated-docs/**/*', allowEmptyArchive: true
        }
    }
}

この設定では、ビルドとテストが実行され、Spring REST Docsによって生成されたスニペットを元にAsciidoctorがHTMLドキュメントを作成します。生成されたドキュメントはarchiveArtifactsステップでアーカイブされ、Jenkinsの成果物として保存されます。

GitLab CIへの統合例

GitLab CIでも同様に、.gitlab-ci.ymlにパイプラインを設定することで、Spring REST Docsを利用したドキュメント生成を自動化できます。

stages:
  - build
  - test
  - docs

build:
  stage: build
  script:
    - mvn clean install

test:
  stage: test
  script:
    - mvn test

generate_docs:
  stage: docs
  script:
    - mvn asciidoctor:process-asciidoc
  artifacts:
    paths:
      - target/generated-docs/

この設定では、generate_docsステージでSpring REST Docsのスニペットを基にAsciidoctorを使用してHTMLドキュメントが生成され、その成果物がtarget/generated-docs/に保存されます。これにより、パイプラインの最終段階で常に最新のAPIドキュメントが生成されます。

CI/CDでの成果物の公開

生成されたAPIドキュメントを公開するためには、成果物を適切な場所にデプロイする必要があります。これは、社内の共有サーバーやS3バケットなどのクラウドストレージ、あるいは静的サイトホスティングサービス（GitHub PagesやNetlifyなど）にデプロイすることで実現できます。

たとえば、Jenkinsを使用してHTMLドキュメントをS3バケットにアップロードする場合、Jenkinsfileに以下のようなステップを追加します。

post {
    success {
        s3Upload(
            file: 'target/generated-docs/',
            bucket: 'your-s3-bucket',
            path: 'docs/'
        )
    }
}

この設定により、生成されたドキュメントがS3バケットに自動的にアップロードされ、APIドキュメントがWeb上で公開されます。

CI/CD統合の利点

Spring REST DocsをCI/CDパイプラインに統合することで、APIの更新が行われるたびにドキュメントが自動的に最新の状態に保たれます。これにより、開発者や利用者は常に正確で最新のドキュメントにアクセスできるようになり、開発フロー全体が効率的かつ信頼性の高いものになります。

  • 常に最新のドキュメント: APIの変更がドキュメントに即座に反映され、開発とドキュメントの乖離を防ぎます。
  • 自動化による負担軽減: 手動でのドキュメント更新が不要になり、開発者の負担が軽減されます。
  • 信頼性の向上: ドキュメントの生成がテストと同時に行われるため、APIの動作とドキュメントが常に一致した状態を保てます。

このように、Spring REST DocsをCI/CDパイプラインに統合することで、APIドキュメンテーションのプロセスが自動化され、ドキュメントの信頼性とメンテナンス性が大幅に向上します。

応用例：APIバージョン管理

APIのバージョン管理は、サービスが成長し、変更が必要になった際に重要な役割を果たします。Spring REST Docsを使用して、異なるAPIバージョンごとにドキュメントを生成・管理することも可能です。ここでは、Spring REST Docsを活用して、APIバージョンごとのドキュメントを管理する方法について説明します。

APIバージョニングの実装

まず、APIバージョンごとにエンドポイントを分ける方法を見ていきます。典型的には、URLパスにバージョン番号を含めてエンドポイントを定義します。

@RestController
@RequestMapping("/api/v1")
public class GreetingControllerV1 {

    @GetMapping("/greetings")
    public ResponseEntity<String> getGreeting() {
        return ResponseEntity.ok("Hello from API v1!");
    }
}

@RestController
@RequestMapping("/api/v2")
public class GreetingControllerV2 {

    @GetMapping("/greetings")
    public ResponseEntity<String> getGreeting() {
        return ResponseEntity.ok("Hello from API v2!");
    }
}

この例では、/api/v1/greetingsおよび/api/v2/greetingsというエンドポイントを持つ、異なるバージョンのAPIが実装されています。

バージョンごとのテストコードの実装

APIバージョンごとにドキュメントを生成するためには、それぞれのバージョンのエンドポイントに対してテストを記述します。以下は、異なるバージョンのAPIに対するテストコードの例です。

@WebMvcTest(GreetingControllerV1.class)
public class GreetingControllerV1Test {

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void shouldReturnGreetingForV1() throws Exception {
        this.mockMvc.perform(get("/api/v1/greetings"))
            .andExpect(status().isOk())
            .andExpect(content().string("Hello from API v1!"))
            .andDo(document("v1/greetings", 
                preprocessRequest(prettyPrint()), 
                preprocessResponse(prettyPrint())));
    }
}

@WebMvcTest(GreetingControllerV2.class)
public class GreetingControllerV2Test {

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void shouldReturnGreetingForV2() throws Exception {
        this.mockMvc.perform(get("/api/v2/greetings"))
            .andExpect(status().isOk())
            .andExpect(content().string("Hello from API v2!"))
            .andDo(document("v2/greetings", 
                preprocessRequest(prettyPrint()), 
                preprocessResponse(prettyPrint())));
    }
}

このテストコードでは、それぞれのAPIバージョンに対して異なるスニペット（v1/greetingsやv2/greetings）が生成されるようにしています。これにより、バージョンごとにドキュメントを分けて管理することが可能です。

ドキュメントの統合と生成

バージョンごとのスニペットが生成されたら、それを基にドキュメントを作成します。src/docs/asciidocディレクトリ内に、各バージョンに対応するドキュメントファイルを作成します。

以下は、index.adocに異なるバージョンのAPIドキュメントを統合する例です。

= API Documentation

== Version 1

=== GET /api/v1/greetings
include::{snippets}/v1/greetings-http-request.adoc[]
include::{snippets}/v1/greetings-http-response.adoc[]

== Version 2

=== GET /api/v2/greetings
include::{snippets}/v2/greetings-http-request.adoc[]
include::{snippets}/v2/greetings-http-response.adoc[]

このように、バージョンごとにスニペットを分けて組み込むことで、異なるAPIバージョンのドキュメントを1つのドキュメントに統合できます。これにより、API利用者は各バージョンのAPI仕様を簡単に参照することができます。

APIバージョニングの運用

実際の運用では、APIバージョンごとにドキュメントを更新し、古いバージョンと新しいバージョンが共存する状態を管理することが必要です。Spring REST Docsを利用することで、各バージョンのエンドポイントをテストし、ドキュメントを生成し続けることで、正確で信頼性の高いAPI仕様書を提供できます。

また、CI/CDパイプラインに統合することで、APIの更新が行われるたびにドキュメントが自動的に最新の状態に保たれます。これにより、異なるAPIバージョンを管理しながらも、常に正確なドキュメントを利用者に提供できるようになります。

APIバージョニングの利点

APIのバージョンごとのドキュメントを管理することで、以下の利点があります。

  • 後方互換性の維持: 古いバージョンのAPI利用者が、依然としてそのバージョンに対応したドキュメントを参照できるようにします。
  • 移行の容易さ: 新しいバージョンに移行する際に、開発者や利用者がどの部分が変更されたかを容易に確認でき、スムーズな移行を促進します。
  • ドキュメントの一貫性: バージョン間の仕様の違いを明確に記載することで、API利用者が誤解を生まずに正確な情報を得られます。

このように、Spring REST Docsを活用してAPIバージョニングを管理することで、信頼性の高いAPIドキュメンテーションを提供し、APIの更新や移行を円滑に行うことが可能になります。

ドキュメントの公開

生成されたAPIドキュメントを外部に公開することで、開発者やAPI利用者が最新かつ正確な情報にアクセスできるようになります。Spring REST Docsを使って作成されたドキュメントは、さまざまな方法で公開が可能です。ここでは、APIドキュメントの公開方法と、その際に注意すべきポイントについて説明します。

公開方法の選択

APIドキュメントを公開する際には、どこでどのようにドキュメントをホストするかを決定する必要があります。一般的な方法としては、次の3つのオプションがあります。

  1. 社内サーバーやイントラネットでの公開: セキュリティやアクセス制限が重要な場合、ドキュメントを社内でホストするのが一般的です。この方法は、チーム内でのみドキュメントを共有したい場合に適しています。
  2. クラウドストレージサービスを利用した公開: AWS S3やAzure Blob Storageなどのクラウドストレージを使用して、静的なHTMLファイルとして公開することができます。この方法は、簡単に設定でき、アクセス制御もしやすいため、広く利用されています。
  3. 静的サイトホスティングサービスの利用: GitHub PagesやNetlifyなどのサービスを使用して、APIドキュメントを静的なWebサイトとして公開できます。この方法は、APIの利用者に対して広くドキュメントを公開したい場合に便利です。

GitHub Pagesを使用した公開例

GitHub Pagesを使用して、生成されたAPIドキュメントを公開する方法を説明します。以下の手順で進めることができます。

  1. リポジトリの作成: GitHub上に公開用のリポジトリを作成します。
  2. 生成されたドキュメントをリポジトリにコミット: target/generated-docs/などに生成されたHTMLドキュメントをリポジトリにコミットします。
  3. GitHub Pagesの設定: GitHubリポジトリの設定画面に移動し、「GitHub Pages」セクションで公開するブランチとフォルダーを指定します（例：mainブランチの/docsフォルダを指定）。
  4. 公開URLの確認: GitHub PagesのURLが自動的に生成され、そのURLを利用者に共有することで、APIドキュメントを参照できるようになります。

この方法により、GitHubを使用して簡単にAPIドキュメントを公開することができ、更新があれば再度コミットするだけで自動的に最新のドキュメントが公開されます。

AWS S3を使用した公開例

AWS S3バケットを使ってAPIドキュメントを公開する手順も簡単です。

  1. S3バケットの作成: AWSコンソールから新しいS3バケットを作成します。バケット名は一意である必要があります。
  2. 生成されたドキュメントをアップロード: target/generated-docs/に生成されたHTMLファイルをS3バケットにアップロードします。
  3. バケットの公開設定: アクセス許可を設定し、S3バケット内のドキュメントをインターネット上で公開できるように設定します。静的ウェブサイトホスティングを有効にし、公開URLを取得します。
  4. 公開URLの共有: S3バケットのURLを利用者に提供し、APIドキュメントにアクセスできるようにします。

公開時のセキュリティ対策

APIドキュメントの公開には、適切なセキュリティ対策を講じる必要があります。特に、内部APIや開発中のAPIドキュメントを公開する場合、次の点に注意してください。

  • アクセス制限: ドキュメントへのアクセスを特定のユーザーやIPアドレスに制限することが可能です。AWS S3やGitHub Pagesでは、アクセス制御の設定を使用して公開範囲を制限できます。
  • HTTPSの使用: ドキュメントが公開される際には、HTTPSを使用して安全な接続を確保することが推奨されます。GitHub PagesやAWS S3では、HTTPS接続が自動的に有効になります。
  • 認証機能の導入: 特に社内向けやクローズドな環境でドキュメントを公開する場合、認証機能を追加してアクセスを制限することが重要です。

定期的なドキュメント更新の自動化

CI/CDパイプラインにドキュメント生成と公開プロセスを組み込むことで、APIが更新されるたびに自動的に最新のドキュメントが公開されるようにできます。例えば、JenkinsやGitLab CIを使って、ドキュメントの生成と同時にS3やGitHub Pagesにアップロードするタスクを設定しておけば、手動での公開作業を省くことができます。

公開ドキュメントの管理

APIバージョンごとのドキュメントや、古いドキュメントをどのように扱うかも重要です。次の点を考慮してください。

  • バージョン別ドキュメント: バージョンごとにドキュメントを公開する場合、それぞれのバージョンが明確に識別できるように、URL構造やナビゲーションを工夫しましょう（例：/v1/docs、/v2/docs）。
  • 古いバージョンのドキュメントの管理: 古いバージョンのドキュメントを非公開にするか、引き続きアクセスできるようにするかを事前に決定します。古いAPIを利用するユーザーのために、過去のバージョンも公開しておくのが一般的です。

このように、APIドキュメントを適切に公開・管理することで、利用者が常に最新の情報にアクセスできる環境を提供し、APIの信頼性を向上させることができます。

まとめ

本記事では、Spring REST Docsを使用したAPIドキュメンテーションの自動生成と、その活用方法について詳しく解説しました。Spring REST Docsは、テスト駆動でAPIのドキュメントを生成し、バージョン管理やカスタマイズも容易に行えます。また、CI/CDパイプラインに統合することで、ドキュメントを常に最新の状態に保ち、社内外での公開もスムーズに行うことができます。適切なドキュメント管理は、APIの信頼性と開発プロセスの効率化に寄与するため、プロジェクトにおいて重要な要素です。

Java
ドキュメンテーション REST API Spring

コメント

コメントする

目次
  1. Spring REST Docsとは
    1. ドキュメントの自動生成
    2. RESTful API開発における利点
  2. 必要な環境設定
    1. Mavenプロジェクトの設定
    2. Gradleプロジェクトの設定
    3. その他の必要な設定
  3. サンプルプロジェクトの作成
    1. Spring Bootプロジェクトの作成
    2. シンプルなREST APIの実装
    3. テストの追加
    4. プロジェクトのビルドと実行
  4. REST APIのテスト設計
    1. MockMvcのセットアップ
    2. 基本的なテストケースの作成
    3. 詳細なテストの追加
    4. テスト結果の確認とドキュメント生成
  5. APIエンドポイントのドキュメント化
    1. ドキュメント生成の流れ
    2. スニペットの内容例
    3. 生成されたスニペットの統合
    4. エラーハンドリングとドキュメント化
    5. ドキュメントの構造
  6. スニペットのカスタマイズ
    1. カスタムフィールドの追加
    2. プレプロセッサの使用
    3. テンプレートのカスタマイズ
    4. リクエストとレスポンスの例のカスタマイズ
    5. 組織に合わせたドキュメント形式の作成
  7. 静的HTMLドキュメントの生成
    1. Asciidoctorを使ったドキュメント生成
    2. ドキュメントの構造
    3. HTMLドキュメントの生成
    4. HTMLドキュメントのカスタマイズ
    5. 生成されたドキュメントの確認と活用
  8. CI/CDパイプラインへの統合
    1. CI/CDパイプラインの基本構造
    2. Jenkinsへの統合例
    3. GitLab CIへの統合例
    4. CI/CDでの成果物の公開
    5. CI/CD統合の利点
  9. 応用例：APIバージョン管理
    1. APIバージョニングの実装
    2. バージョンごとのテストコードの実装
    3. ドキュメントの統合と生成
    4. APIバージョニングの運用
    5. APIバージョニングの利点
  10. ドキュメントの公開
    1. 公開方法の選択
    2. GitHub Pagesを使用した公開例
    3. AWS S3を使用した公開例
    4. 公開時のセキュリティ対策
    5. 定期的なドキュメント更新の自動化
    6. 公開ドキュメントの管理
  11. まとめ