目次
Swagger は RESTful API の構造をドキュメント化するための仕様および各種周辺ツール等を提供するプロジェクトです。ドキュメント化された情報をもとに、クライアントアプリケーションのソースコードを自動生成したり、Web UI 形式の API 仕様書を公開したりできます。周辺ツールは様々な言語およびフレームワークに対応しており、ここでは特に Java の Spring Boot に関する利用方法をまとめます。
サンプルプロジェクト構成
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 を内部的に取得して利用します。
関連記事
- Spring Security フォームログインのサンプルコードSpring フレームワークによる Web アプリケーション開発で、ログイン処理を実装する際は Spring Security が便利です。ここでは特に Spring Boot で Web アプリケーションを開発する場合を対象とし、フォームによる ID/Password ログインを行うためのサンプルコードをまとめます。 公式ドキュメント [Spring Security チュートリアル](http...
- Java配列の宣言方法 (C/C++との違い)Javaの配列 Javaの配列宣言方法はC/C++と似ているようで若干異なる。 初期化しない場合 C/C++の int array[10]; はJavaでは int array[] = new int[10]; となる。同様にC/C++の int array[3][3]; はJavaでは int array[][] = new int[3][3]; となる。 初期化
- PlantUML による UML 図の描き方PlantUML はテキスト形式で表現されたシーケンス図やクラス図といった UML (Unified Modeling Language) 図の情報から画像を生成するためのツールです。簡単な使い方をまとめます。 インストール方法の選択 Atom や Eclipse のプラグインをインストールしてエディタから利用する方法、JAR をダウンロードして Java コマンドで実行する方法、Redmine ...
- Akka HTTP サンプルコード (Scala)Akka アクターを用いて実装された汎用 HTTP フレームワークです。Spray の後継です。コアモジュールである akka-http-core は 2016/2/17 に experimental が外れました。akka-http などのいくつかのサブモジュールは 2016/3/1 現在 experimental のままですが、基本的な
- Kestrel の使用例Kestrel は Message Queue (MQ) の実装のひとつです。一般に MQ はアプリケーション間やプロセス間、スレッド間で非同期に通信するために用いられます。メッセージの送信側は MQ に書き込めば受信側の応答を待たずに次の処理に非同期に進むことができます。Kestrel はわずか 2500 行程の Scala で実装されており JVM で動作します。MQ 自体はメモリ上に存在する...