Swagger は RESTful API の構造をドキュメント化するための仕様および各種周辺ツール等を提供するプロジェクトです。ドキュメント化された情報をもとに、クライアントアプリケーションのソースコードを自動生成したり、Web UI 形式の API 仕様書を公開したりできます。周辺ツールは様々な言語およびフレームワークに対応しており、ここでは特に Java の Spring Boot に関する利用方法をまとめます。

• Swagger
  • 公式ドキュメント
  • OpenAPI Specification
• Springfox Reference Documentation
  • Quick start guides
  • Configuring Springfox

サンプルプロジェクト構成

SwaggerConfig.java を追加します。

.
|-- build.gradle
|-- gradle
|   `-- wrapper
|       |-- gradle-wrapper.jar
|       `-- gradle-wrapper.properties
|-- gradlew
|-- gradlew.bat
`-- src
    `-- main
        `-- java
            `-- hello
                |-- Application.java
                |-- HelloController.java
                `-- SwaggerConfig.java

build.gradle

springfox-swagger2 および springfox-swagger-ui を利用します。

buildscript {
    ext {
        springBootVersion = '1.5.3.RELEASE'
    }
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
    }
}

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'idea'
apply plugin: 'org.springframework.boot'

jar {
    baseName = 'gs-spring-boot'
    version =  '0.1.0'
}

repositories {
    mavenCentral()
}

sourceCompatibility = 1.8
targetCompatibility = 1.8

dependencies {
    compile('org.springframework.boot:spring-boot-starter-web')
    compile('io.springfox:springfox-swagger2:2.7.0') // http://localhost:8080/v2/api-docs が利用可能になります。
    compile('io.springfox:springfox-swagger-ui:2.7.0') // http://localhost:8080/swagger-ui.html が利用可能になります。
}

Java ソースコード

Swagger の機能で API 仕様を解析およびドキュメント化する対象となる、Swagger とは直接的には関係のない、通常の Spring Boot プロジェクトです。

Application.java

Spring Boot のエントリーポイントとなるクラスです。

package hello;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

HelloController.java

package hello;

import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;

@RestController
public class HelloController {

    // すべての HTTP メソッドに対応
    @RequestMapping("/")
    public String index() {
        return "Greetings from Spring Boot!";
    }

    // GET のみ対応
    @GetMapping("/getsample")
    public String getSample() {
        return "ok getsample";
    }

    // POST のみ対応
    @PostMapping("/postsample")
    public String postSample() {
        return "ok postSample";
    }
}

Swagger 設定ファイル

SwaggerConfig.java

『What Is Swagger?』および『OpenAPI Specification』でまとめられている情報を以下のエンドポイントにおいて JSON 形式で返すための設定です。既定では認証設定がなされておらず、情報漏洩に注意します。

http://localhost:8080/v2/api-docs

package hello;

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

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket document() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("Example API")
            .version("1.0")
            .build();
    }
}

io.springfox:springfox-swagger-ui によって導入された Swagger UI は以下のエンドポイントで利用できます。上記設定による JSON を内部的に取得して利用します。

http://localhost:8080/swagger-ui.html