Springdoc-openapiでAPIドキュメントを自動生成する

Spring

2021/07/23 21:352021/07/23 21:35

Springdoc-openapiを使ってSpring Bootで実装したアプリケーションのAPI仕様書を実装コードから自動生成する。

API仕様書はIF部分に修正があるたびにメンテしてあげる必要があるが、メンテが疎かになると実装と乖離した内容となるため、実装コードベースで管理することで保守性が高まることを期待する。

また、springdoc-openapiにはSwagger UIでAPIドキュメントを表示することができる機能があるが、Redocが見た目的に好みなのでRedocで表示させる。

環境

導入

build.gradle

springdoc-openapi-uiを依存関係に追加

build.gradledependencies {
    // 以下を追加
    implementation 'org.springdoc:springdoc-openapi-ui:1.5.10'
}

Bean登録

OpenAPIのBeanを登録するためのOpenApiBeanConfigurationクラスを新規追加する。

OpenApiBeanConfiguration.javaimport io.swagger.v3.oas.models.OpenAPI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiBeanConfiguration {

    @Bean
    public OpenAPI restApi() {
        return new OpenAPI();
    }
}

最低限動作させるための導入は上記作業で完了。

機能

OpenAPIドキュメント取得

アプリケーションを起動して以下のエンドポイントにアクセスするとOpenAPIのドキュメントが取得できる。
json形式で取得：/v3/api-docs
yaml形式で取得：/v3/api-docs.yaml

Swagger UIの表示

アプリケーションを起動して/swagger-ui/index.htmlにアクセスするとAPIドキュメントをSwagger UI上で表示できる。

springdoc拡張設定

application.ymlにspringdocの各種設定を追加することができる。

application.ymlspringdoc:
  api-docs:
    path: /api-docs # デフォルトの/v3/api-docsのエンドポイントから任意のエンドポイントに変更。
  swagger-ui:
    enabled: false # Swagger UIの有効/無効の切り替え。

追加できるプロパティは公式ドキュメントを参照。
Springdoc-openapi Properties

OpenAPIドキュメントの拡張

OpenAPIが提供しているアノテーションを付与することで拡張が可能。
OpenAPI Specification

REST APIの情報を指定

@OperationアノテーションをControllerのメソッドに付与する。
APIのタイトルや概要説明の定義などが可能。

@Operation(summary = "メモ取得API", description = "メモ情報の取得と返却を行う")
@GetMapping(path = "/memo", produces = "application/json")
public ResponseEntity<MemoResponse> getArticle() {}

スキーマ定義の情報を指定

@Schemaアノテーションをリクエスト/レスポンスのプロパティに付与する。
プロパティ名、サンプル値、最大最小値、初期値、必須可否、などの指定が可能。

import io.swagger.v3.oas.annotations.media.Schema;

public class MemoResponse {

    @JsonProperty("title")
    @Schema(description = "メモタイトル", example = "タイトル1", required = true)
    private String title;

    @JsonProperty("text")
    @Schema(description = "メモ本文", example = "本文1")
    private String text;
}

Redocで表示

spec-urlには、/api-docsのエンドポイントから取得したjsonを指定する。

index.html<!DOCTYPE html>
<html lang="en">
<head>
    <title>Redoc</title>
    <meta charset="utf-8"/>
    <meta name="robots" content="noindex, nofollow, noarchive"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
</head>
<body>
    <redoc spec-url="./api-docs.json"></redoc>
    <script src="https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js"> </script>
</body>
</html>

あとは任意のサービスで上記のhtmlを公開して共有するだけ。
チーム開発であればCI/CD処理でOpenAPIのドキュメントを吐き出して、GitHub Pagesで公開するのが良さそう。