Spring BootのRest APIサービスにSwaggerによるドキュメント定義を追加してみた

Spring BootのRest APIサービスのドキュメントを定義したり、API実行を行ったりできるためのライブラリに、Swaggerがある。

今回は、STS(Spring Tool Suite)を利用したSpring Bootアプリケーション上で動作するRest APIサービス上で、Swaggerによるドキュメント定義を追加してみたので、そのサンプルプログラムを共有する。

前提条件

下記記事の実装が完了していること。

Spring BootのRest APIサービスでXML形式を取り扱えるようにしてみたこれまでこのブログで紹介してきたRestAPIサービスでは、JSON形式でリクエストボディの送信と結果の受信を行ってきたが、XML形式で...

作成したサンプルプログラムの内容

作成したサンプルプログラムの構成は以下の通り。

なお、上記の赤枠は、前提条件のプログラムから変更したプログラムである。

pom.xml(追加分)の内容は以下の通りで、REST APIのドキュメントを定義するSwaggerというライブラリを追加している。

<!-- Swaggerを利用するためのライブラリを追加 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

application.propertiesの内容は以下の通りで、Spring Boot 2.6.2でSpring Fox3.0.0を動かすために必要な設定を追加している。

# ポート番号：8085で起動するよう設定
server.port=8085

# Oracle DBの接続先を設定
spring.datasource.url=jdbc:oracle:thin:@localhost:1521:xe
spring.datasource.username=USER01
spring.datasource.password=USER01
spring.datasource.driverClassName=oracle.jdbc.driver.OracleDriver

# エラーメッセージのファイル名(messages.properties)を指定
spring.messages.basename=messages

# Spring Boot 2.6.2でSpring Fox3.0.0を動かすために必要な設定
spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

Swaggerの定義ファイルの内容は以下の通りで、API情報やAPIのデータタイプを設定している。

package com.example.demo;

import java.util.Arrays;
import java.util.HashSet;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class DemoSwaggerConfig {

    private HashSet<String> consumesAndProduces = new HashSet<String>(
            Arrays.asList("application/json", "application/xml"));
    
    @Bean
    public Docket api() {
        // Swaggerでドキュメント生成に必要な設定を生成し返却
        return new Docket(DocumentationType.SWAGGER_2)
                   // API情報を設定
                .apiInfo(apiInfo())
                   // 送信するAPIのデータタイプを設定
                .consumes(consumesAndProduces)
                   // 受信するAPIのデータタイプを設定
                .produces(consumesAndProduces);
    }
    
    private ApiInfo apiInfo() {
        // API情報を生成し返却
        return new ApiInfoBuilder()
                // タイトル・詳細説明・APIバージョン
            .title("ユーザー情報登録・更新API")
            .description("ユーザー情報の登録・更新・削除ができるAPIです")
            .version("1.0.0")
                // 連絡先(連絡先名・サイトURL・メールアドレス)
            .contact(new Contact("purin-it"
                    , "https://www.purin-it.com", "tagyo483@f5.si"))
                // ライセンス名・ライセンスURL
            .license("Apache 2.0")  
            .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
            .build();
      }
}

その他のソースコード内容は、以下のサイトを参照のこと。
https://github.com/purin-it/java/tree/master/spring-boot-rest-api-swagger/demoRestApi