74
72

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 5 years have passed since last update.

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

Posted at

■環境

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

  • 構築イメージ

swagger1.png

  • Spring Bootでの構築イメージ

swagger2.png

■SpringFox

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

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

SpringFox by springfox

■構築手順

1.必要なライブラリをダウンロード

Mavenの場合、pom.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>

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仕様書の完成

引用元
swagger4.png

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

swagger3.png

■What's Swagger UI?

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

Swagger UI – Swagger

■応用編

■オフラインドキュメントにする

  • Swagger Editorを使用する

swagger5.png

Swagger Editor – Swagger

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

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

io.swagger.annotations (swagger-annotations 1.5.0 API)

■参考資料

Spring Boot と Swagger #渋谷java // Speaker Deck

Spring MVC integration for Swaggerのバージョン2をSpringBootで実行する - Qiita

74
72
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
74
72

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?