Spring Boot でSwagger を使う方法

Spring Boot でSwagger を使う方法

Swaggerを使うにはbuild.gradleに以下2行を追加します。

dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-web'
  implementation 'io.springfox:springfox-swagger2:2.9.2' // 追加
  implementation 'io.springfox:springfox-swagger-ui:2.9.2' // 追加

  testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

コンフィグファイル作成

SwaggerConfig.java(ファイル名は任意)というファイルを作成します。

package jp.co.confrage;

import javax.servlet.ServletContext;

import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

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

@Configuration
@EnableSwagger2
@EnableConfigurationProperties(SwaggerProperties.class)
public class SwaggerConfig {
  @Bean
  public Docket doc() {
    return new Docket(DocumentationType.SWAGGER_2)
        .protocols(prop.getProtocols())
    .pathProvider(pathProvider(cxt))
    .apiInfo(apiInfo())
    .select()
    .build();
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
      .title("サンプル API")
      .description("説明です~")
      .version("1.0")
      .build();
  }

  /* APIのベースパス */
  private PathProvider pathProvider(ServletContext cxt) {
    return new RelativePathProvider(cxt) {
      @Override
      public String getApplicationBasePath() {
        return "/";
      }
    };
  }
}

@EnableSwagger2アノテーションを忘れずにつけます。

必要に応じてSwaggerConfigに対するプロパティファイルを作成します。(特に不要ですが)

ここでは、SwaggerProperties.javaとします。

package jp.co.confrage;

import java.util.HashSet;
import java.util.Set;

import org.springframework.boot.context.properties.ConfigurationProperties;
import lombok.Data;

@Data
@ConfigurationProperties(prefix="swagger")
public class SwaggerProperties {
  private String host = "localhost:8080";
  private String protcol = "http";
  private String basePath = "/";

  /* APIプロトコルを取得 */
  public Set<String> getProtocols() {
    Set<String> protocols = new HashSet<>();
    protocols.add(protcol);
    return protocols;
  }
}

コントローラー

GETとPOSTのRestControllerを作成します。

package jp.co.confrage;

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

@RestController
public class DemoController {

  @GetMapping(value = "/getMethod")
  public String get() {
    return "google";
  }

  @PostMapping(value = "/postMethod")
  public String post() {
    return "yahoo";
  }
}

Spring Bootアプリケーションを実行して、http://localhost:8080/swagger-ui.htmlにアクセスすると、SwaggerのHTML画面が表示されます。

Spring Boot でSwagger を使う方法

サンプルAPIの下にあるリンクをクリックするとapi-doc.jsonがダウンロードされます。

参考サイト

buid.gradleでapiclientを自動生成する

build.gradleのタスクを作成してswagger codegenよりsdkを自動生成することが可能です。

build.gradleに以下のタスクを追加します。

buildscript {
    ext {
        springBootVersion = '2.1.2.RELEASE'
    }
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
        classpath("io.swagger:swagger-codegen:2.3.1") // これを追加する必要がある
    }
}

task generate(group:'swagger',description:'説明文を書きます'){
  def in  = file('apidoc/apidoc.json')
  def out = file('build/sdk')

  inputs.file(in)
  outputs.file(out)
  doLast{
    def conf = new io.swagger.codegen.config.CodegenConfigurator();
    conf.setInputSpec(in.path)
    conf.setOutputDir(out.path)
    conf.setLang('java')
    conf.setAdditionalProperties(
      'apiPackage': "${project.group}.confrage.api.client".toString(),
      'modelPackage':"${project.group}.confrage.api.model".toString(),
      'invokerPackage':"${project.group}.confrage.api.invoker".toString(),
      'groupId': project.group,
      'artifactId': "${project.name}-sdk".toString(),
      'artifactVersion': 1.0.0,
      'library': 'resttemplate',
      'dateLibrary': 'java8-localdatetime'
    )
  }
}

これでタスクを実行すればbuild配下にプロジェクトが生成されます。

springdoc-openapi

Just a moment...

springdoc-openapi

バージョン3からOpen APIと名称が変わったようです。springdoc-openapi-uiライブラリを使用してAPIドキュメントを生成します。

build.gradleに以下1行を追加します。

dependencies {
  implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.5.10'
  // .... 
}

Spring Bootアプリケーションを実行して、http://localhost:8080/swagger-ui.htmlにアクセスすると空のAPIドキュメント(Swagger UI)が表示されます。

Spring Boot でSwagger を使う方法

applicaion.yml

パスの変更やSwagger UIの無効化など、いくつか設定変更することが出来ます。

springdoc:
  swagger-ui:
    path: /aaa.html

これで、http://localhost:8080/aaa.htmlでSwagger UIにアクセスできるようになります。

springdoc:
  api-docs:
    path: /hoge

JSONのパスを/hogeに変更します。http://localhost:8080/hogeでJSONにアクセスすることが出来るようになります。

Spring Boot でSwagger を使う方法

コメント

タイトルとURLをコピーしました