■環境
Spring Boot 1.2.5.Release
Java 8
Maven 3.3.1
Swagger
■概要
Swaggerを使って、WebAPI仕様書をラクラク生成する。
1.必要なライブラリをダウンロード
2.設定内容を記述
生成対象のWebAPI指定など数行レベル
3.アプリケーションをビルド
4.オンラインのWebAPI仕様書の完成
■What's Swagger?
- REST API(Web API)の記述に関する仕様とそれに関連するツールの総称。
Swagger – The World's Most Popular Framework for APIs.
- RESTful APIの記述標準化にSwaggerが採用される可能性が高い。
RESTful APIの記述標準化を目指す「Open API Initiative」をマイクロソフト、Google、IBMらが立ち上げ。Swaggerをベースに - Publickey
- 構築イメージ
- Spring Bootでの構築イメージ
■SpringFox
-
SpringフレームワークでWebAPIのドキュメント(JSON)生成を自動化してくれるライブラリ
-
Swaggerの設定を行うために使用
■構築手順
1.必要なライブラリをダウンロード
Mavenの場合、pom.xmlに下記内容を追加します。
<dependencies>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.0.3</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.0.3</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-core</artifactId>
<version>1.5.4</version>
</dependency>
</dependencies>
2.設定内容を記述
Swagger準拠のJSONを出力する設定を記述するJavaファイルを作成する。
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import com.google.common.base.Predicate;
import com.google.common.base.Predicates;
@Configuration
@EnableSwagger2 // swagger(v2)を有効にする
public class Swagger2Config {
@Bean
public Docket swaggerSpringMvcPlugin() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.paths(paths())
.build()
.apiInfo(apiInfo());
}
private Predicate<String> paths() {
// 仕様書生成対象のURLパスを指定する
return Predicates.and(
Predicates.not(Predicates.containsPattern("/hogehoge-view")),
Predicates.or(
Predicates.containsPattern("/data/*"),
Predicates.containsPattern("/authority/*"),
Predicates.containsPattern("/file/*")));
}
private ApiInfo apiInfo() {
ApiInfo apiInfo = new ApiInfo(
"HogeHoge System Web API", // title
"HogeHoge System の Web API 仕様書", // description
"0.0.1", // version
"", // terms of service url
"HogeHoge", // created by
"HogeHoge Co. Ltd", // license
""); // license url
return apiInfo;
}
}
3.アプリケーションをビルド
ビルドしてください!
4.オンラインのWebAPI仕様書の完成
ビルド完了後、 /swagger-ui.htmlにアクセスすることでオンラインでWebAPI仕様書を見ることができる。
これは、Swagger UIを介して見ていることになる。
■What's Swagger UI?
- Swagger準拠のJSONから動的にWebAPI仕様書を生成するツール
■応用編
■オフラインドキュメントにする
- Swagger Editorを使用する
1.http://editor.swagger.io/ に接続する
2.[File]メニュー – [Import File...]を選択
3.参照ボタンを押下し、Swagger準拠のJSON/YAMLファイル を選択
4.Import ボタンを押下する
5.[Generate Client]メニュー – HTML を選択
6.zipファイルがダウンロードされる。
- 解凍したzipファイル内のindex.htmlがWebAPI仕様書である
- デザインはSwagger UIより簡素
■仕様書の内容をカスタマイズする
具体的には以下のAPIを駆使する。
io.swagger.annotations (swagger-annotations 1.5.0 API)
■参考資料
Spring Boot と Swagger #渋谷java // Speaker Deck
Spring MVC integration for Swaggerのバージョン2をSpringBootで実行する - Qiita