Spring Boot でSwagger を使う方法
Swaggerを使うにはbuild.gradleに以下２行を追加します。
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画面が表示されます。
サンプル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
バージョン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)が表示されます。
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にアクセスすることが出来るようになります。
KHI入社して退社。今はCONFRAGEで正社員です。関西で140-170/80～120万から受け付けております^^
得意技はJS(ES6),Java,AWSの大体のリソースです
コメントはやさしくお願いいたします^^
座右の銘は、「狭き門より入れ」「願わくは、我に七難八苦を与えたまえ」です^^
コメント