Spring Bootで実装したREST APIから一瞬でAPIドキュメントを生成

はじめに

SpringBoot初心者向けです。マイクロサービスの実装にSpringBootを使うケースは多いと思いますが、最近勉強し始めた初心者にとって、UIの無いサービス開発って何となく心理的なハードルが高かったりするのではないでしょうか。（ん？そんなことないよ、という方はスルーしてくださいww）

その心理的ハードルが何かというと、APIテストの前にサクッとうまく動くかテストしたいよね、という時にCurlでコマンドを打たなければならないということ。普段からCurlはよく使ってるよ、というケースを除けば、毎回それなりに長めのコマンドを書き方を思い出しながら（もしくは調べながら）タイプするのはとても面倒です。

そんな初心者にとって、その面倒な部分を一瞬で解消できるのがSwagger-uiです。APIドキュメントの作成ツールとしてはデファクトになりつつあると思っていますが、このSwagger-uiは、既に出来ているソースに数行追加するだけで、簡単に自動生成出来てしまいます。しかもこのSwagger-uiを使えば、GUIでAPIの簡単なテストも出来てしまいます。（実際には後ろでCurl叩いてくれている訳ですが）

という訳でSpringBootで作成したREST APIからSwagger-uiを生成するまでの流れをまとめておきます。（自分の備忘メモとして）

依存関係

Mavenを使っています。以下の依存関係をpom.xmlに追加します。

pom.xml

<pom>
    <repositories>
        <repository>
          <id>jcenter-snapshots</id>
          <name>jcenter</name>
          <url>https://jcenter.bintray.com/</url>
        </repository>
    </repositories>

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
</pom>

今回は現時点（2020/10/13）で最新のSpringfox3.0.0を使用しています。3系へのバージョンアップで最低限必要なアノテーションの数も減りました。とりあえずサクッとという用途であれば、依存関係にこの設定を追加するだけでSwagger-uiは起動します。

Configに説明用のBeanを追加

依存関係の設定のみだとerror-basic-controllerが表示されてしまうので、それを除きたい場合は、以下のように@Configurationアノテーションを付けているConfigクラスに@Beanアノテーションを付けたDocketクラスを追加しておきます。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RestController;

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class MicroserviceConfig {

	@Bean
	public Docket customImplementation() {
		return new Docket(DocumentationType.SWAGGER_2)
				.select()
				.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
				.paths(PathSelectors.any())
				.build();
	}
}

今回は省略していますが、上記DocketクラスではAPI内容の説明などの記載もできますので、その辺はまた興味があれば調べてみてください。

Swagger-uiを表示

これであとは、SpringBootを起動して http://localhost:8080/swagger-ui/ にアクセスすると以下の画面が表示されます。

あとはポチポチとGUIでJSONファイルの中身を編集して実行すれば、サクッと簡単な疎通確認は出来てしまいます。

おわりに

こんな簡単にできるなんて素晴らしいですね。Springfox3系は以前のバージョンよりも手間が減っているので、より導入のハードルは下がっていると思います。初心者の方には特におススメです。当記事が少しでも誰かの参考になれば幸いです。