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>

<groupId>io.springfox</groupId>

<artifactId>springfox-boot-starter</artifactId>

</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

# ポート番号：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();
      }
}

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

【PR】「Filmora」は初心者でも本格的な動画編集ができる大変便利なツールだった「Filmora」は初心者でも使いやすい動画編集ツールで、テンプレートとして利用できるテキスト・動画・音楽などが充実していると共に、複数...

サンプルプログラムの実行結果

サンプルプログラムの実行結果は、以下の通り。

1) 接続先となるOracleデータベース上に、以下のUSER_DATAテーブルとデータを作成しておく。

2) Spring Bootアプリケーションを起動した後で、URL「http://localhost:8085/swagger-ui/」にアクセスすると、以下の画面が表示される。

3) 上図で「basic-error-controller」「demo-rest-controller」を開くと、以下の画面が表示される。

4)「demo-rest-controller」内の「/users (getAllUserData)」を開くと、以下の画面が表示されるため、「Try it out」ボタンを押下する。

5) レスポンスタイプが「application/json」のまま、「Execute」ボタンを押下すると、以下のように、USER_DATAテーブルの値がJSON形式で返却されることが確認できる。

上図で「Download」リンクを押下すると、以下のように、レスポンスとして返却されたJSONデータが出力されることが確認できる。

6) レスポンスタイプを「application/xml」に変更後、「Execute」ボタンを押下すると、以下のように、USER_DATAテーブルの値がXML形式で返却されることが確認できる。

上図で「Download」リンクを押下すると、以下のように、レスポンスとして返却されたXMLデータが出力されることが確認できる。

7)「demo-rest-controller」内の「/users/hateoas (saveUserDataHateoas)」を開くと、以下の画面が表示されるため、「Try it out」ボタンを押下する。

8) パラメータタイプ・レスポンスタイプが両方JSON形式の状態で、追加するデータを設定後、「Execute」ボタンを押下すると、以下のように、レスポンスデータがJSON形式で返却されることが確認できる。

上図で「Download」リンクを押下すると、以下のように、レスポンスとして返却されたJSONデータが出力されることが確認できる。

9) パラメータタイプ・レスポンスタイプが両方XML形式の状態で、追加するデータを設定後、「Execute」ボタンを押下すると、以下のように、レスポンスデータがXML形式で返却されることが確認できる。

上図で「Download」リンクを押下すると、以下のように、レスポンスとして返却されたXMLデータが出力されることが確認できる。

10) パラメータタイプ・レスポンスタイプが両方XML形式の状態で、追加するデータがエラーの状態を設定後、「Execute」ボタンを押下すると、以下のように、エラーレスポンスがXML形式で返却されることが確認できる。

上図で「Download」リンクを押下すると、以下のように、レスポンスとして返却されたXMLデータが出力されることが確認できる。

11) パラメータタイプ・レスポンスタイプが両方JSON形式の状態で、追加するデータがエラーの状態を設定後、「Execute」ボタンを押下すると、以下のように、エラーレスポンスがJSON形式で返却されることが確認できる。

上図で「Download」リンクを押下すると、以下のように、レスポンスとして返却されたJSONデータが出力されることが確認できる。

12) 2)～11)までの操作を実行後に、接続先となるOracleデータベース上のUSER_DATAテーブルを確認すると、以下のようにID=4,ID=5のデータが追加され、ID=6のデータが追加されていないことが確認できる。

要点まとめ

Spring BootのRest APIサービスでSwaggerを利用すると、APIのドキュメントを定義したり、API実行を行ったりすることができる。

前提条件

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

サンプルプログラムの実行結果

要点まとめ

Spring Bootでチェック処理を追加したRest APIサービスを呼び出してみた

Spring BootのWEB画面上でREST APIを使ってリストを取得してみた

Spring BootのRest APIサービスで利用している、Swaggerによるドキュメント定義を編集してみた

Spring BootのRest APIサービスでURL情報を追加するHATEOASを利用してみた

Spring BootのRest APIサービスをXML形式で呼び出してみた

Spring BootのRest APIサービスでXML形式を取り扱えるようにしてみた