Spring Bootで作ったWebAPIのマニュアルをswagger2でさくっと作ってみる

前回、WebAPIの作り方を書いて、WebAPIのマニュアルもさくっと作れるみたいなのでswagger2を試してみた。

swaggerは世界で最もポピュラーなAPIのためのフレームワークを自称しています。すごく簡単に設定できてWebUIがついたAPIのマニュアルが簡単に作れるフレームワークです。さらに、springfoxという名前でSpring対応もされています。

作るもの

前回作ったUserを操作するAPIのマニュアルを生成してみる。

ソースはここ

設定

マニュアルを参考に以下を追加します。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.5.0</version>
</dependency>

ココを参考にSwagger2のJavaConfigを追加。

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket swaggerSpringMvcPlugin() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("business-api")
                .select()
                        .paths(paths()) // and by paths
                        .build()
                        .apiInfo(new ApiInfo("Web API",
                                "This is Web API",
                                "1.0.0",
                                "http://localhost:8080/api",
                                "ishii@ishii.tech",
                                "Apache License, Version 2.0",
                                "http://www.apache.org/licenses/LICENSE-2.0"));
    }
    private Predicate<String> paths() {
        return or(regex("/api/users.*"));
    }
}

ApiInfoが何故かDeprecatedとなっている。理由は不明だがjavadocを見るとApiInfoが2つある。

import springfox.documentation.service.ApiInfo;

@Deprecated
public ApiInfo(java.lang.String title,
                  java.lang.String description,
                  java.lang.String version,
                  java.lang.String termsOfServiceUrl,
                  java.lang.String contactName,
                  java.lang.String license,
                  java.lang.String licenseUrl)

もう1つのApiInfoが正解っぽいけど、追加した2つのdependencyには以下のクラスが何故か無いので、上のDeprecatedのクラスを使った。

import springfox.documentation.swagger1.dto.ApiInfo;

確認

起動

./mvnw clean spring-boot:run

WebUI

起動後以下のURLにブラウザで接続するとWebUIが表示される。

http://localhost:8080/swagger-ui.html

表示される画面のイメージ。

前回作ったWebAPIの一覧が並んでいることがわかる。

GET /api/users => 全User取得 (getUsers)
GET /api/users/{id} => idのUserを取得 (getUser)
POST /api/users => Userを追加 (createUser)
PUT /api/users/{id} => Userの更新 (updateUser)
DELETE /api/users/{id} => idのUserを削除 (deleteUser)

更にAPIを選択すると詳細が表示され、その場で実行することもできる。モデルのプロパティーや項目が正しく設定されているかもWebUIでさくっと確認できるようになっている。まぁ、UnitTestを書くとは思うのですが、WebUIから実行や確認ができるのはかなり嬉しい機能です。

画面の表示項目の値や文章についても個別に細かく設定できるみたいなのでカスタマイズ性はよさそうです。

おわり。