Spring Boot環境でWebAPI仕様書をラクラク生成♪

# ■環境
Spring Boot 1.2.5.Release
Java 8
Maven 3.3.1
Swagger

# ■概要
Swaggerを使って、WebAPI仕様書をラクラク生成する。

１．必要なライブラリをダウンロード

２．設定内容を記述
　生成対象のWebAPI指定など数行レベル

３．アプリケーションをビルド

４．オンラインのWebAPI仕様書の完成

# ■What's Swagger？

- REST API(Web API)の記述に関する仕様とそれに関連するツールの総称。

[Swagger – The World's Most Popular Framework for APIs.](http://swagger.io/)

- RESTful APIの記述標準化にSwaggerが採用される可能性が高い。

[RESTful APIの記述標準化を目指す「Open API Initiative」をマイクロソフト、Google、IBMらが立ち上げ。Swaggerをベースに － Publickey](http://www.publickey1.jp/blog/15/open_api_initiative.html)

- 構築イメージ

![swagger1.png](https://qiita-image-store.s3.amazonaws.com/0/70897/552ed4bd-beb5-583d-a879-6d882d8fe833.png)

- Spring Bootでの構築イメージ

![swagger2.png](https://qiita-image-store.s3.amazonaws.com/0/70897/89a47063-63d3-af89-fc77-8f38f489f9ee.png)

# ■SpringFox

- SpringフレームワークでWebAPIのドキュメント(JSON)生成を自動化してくれるライブラリ

- Swaggerの設定を行うために使用

[SpringFox by springfox](http://springfox.github.io/springfox/)


# ■構築手順

１．必要なライブラリをダウンロード

Mavenの場合、pom.xmlに下記内容を追加します。

```xml: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>
```

２．設定内容を記述

Swagger準拠のJSONを出力する設定を記述するJavaファイルを作成する。

```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;
	}
}
```

３．アプリケーションをビルド

ビルドしてください！

４．オンラインのWebAPI仕様書の完成

[引用元](http://petstore.swagger.io/)
![swagger4.png](https://qiita-image-store.s3.amazonaws.com/0/70897/ff1dd14a-c356-c917-eaea-55b8e17df6d2.png)

ビルド完了後、 /swagger-ui.htmlにアクセスすることでオンラインでWebAPI仕様書を見ることができる。
これは、Swagger UIを介して見ていることになる。

![swagger3.png](https://qiita-image-store.s3.amazonaws.com/0/70897/f65bdcd0-c90c-1b47-3e18-d22a712c4622.png)

# ■What's Swagger UI？

- Swagger準拠のJSONから動的にWebAPI仕様書を生成するツール

[Swagger UI – Swagger](http://swagger.io/swagger-ui/)

# ■応用編
#### ■オフラインドキュメントにする

- Swagger Editorを使用する

![swagger5.png](https://qiita-image-store.s3.amazonaws.com/0/70897/55f4d4be-2eaf-d65b-8645-7e07464a1c97.png)

[Swagger Editor – Swagger](http://swagger.io/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より簡素

#### ■仕様書の内容をカスタマイズする

![swagger6.png](https://qiita-image-store.s3.amazonaws.com/0/70897/f4b9ef6c-bf29-4027-88fd-eedff430625f.png)

具体的には以下のAPIを駆使する。

[io.swagger.annotations (swagger-annotations 1.5.0 API)](http://docs.swagger.io/swagger-core/v1.5.0/apidocs/io/swagger/annotations/package-summary.html)

# ■参考資料
[Spring Boot と Swagger #渋谷java // Speaker Deck](https://speakerdeck.com/bati11/spring-boot-to-swagger-number-shibui-gu-java)

[Spring MVC integration for Swaggerのバージョン２をSpringBootで実行する - Qiita](http://qiita.com/c9katayama/items/4d91396a26408e108de0)