こんにちは！ぐち（@bloguchi）です。

前回ご紹介したSpring bootで作るRESTfulなAPIのドキュメントを自動で生成してくれる便利なライブラリをご紹介します。

前回の記事はこちらからどうぞ。

ぶろぐち

 

2 Users

Spring BootでRESTfulなWeb Serviceを作るチュートリアルをやってみた

https://www.bloguchi.info/1633

こんにちは！ぐち（@bloguchi）です。タイトルの通りなんですが、下記のSpringの公式サイトに記載のあるチュートリアルをやってみたのでご紹介します。前提条件僕、英語できないんで誤訳とか意味の取り違い、奇想天外な解釈など思いっきり出てくると思いますが、結果的にちゃんと動くので、そういう目で温かく見てくださいね。笑あくまでも英語なんてからっきしできない社会人がノリと勢いだけで英語のチュートリアルに取り組んでみた戦記だと思って頂ければちょうどかもしれません。（何がちょうどなんだよ）ちなみにGradleのインスト...

Swagger

Web APIのドキュメントとブラウザからリクエストを実行できるようなページを生成してくれるライブラリがあります。Swaggerというものですが、それをSpringと合わせて使えるようにしたのがSpring Fox(と認識しています。笑)です。

Swaggerに関しては公式サイトを見てください。

swagger.io

 

528 Shares

291 Users

5004 Pockets

World's Most Popular API Framework | Swagger

https://swagger.io

Swagger aides in development across the entire API lifecycle, from design and documentation, to test and deployment. Try it today!

Spring Foxのサイトはこちらです。

springfox.github.io

 

12 Shares

4 Users

86 Pockets

SpringFox by springfox

http://springfox.github.io/springfox/

プロジェクトに導入

では、早速プロジェクトに導入しましょう。前回チュートリアルで作成したプロジェクトに追加していきましょう。

まずはbuild.gradleに追加します。dependenciesに下記のように追加してください。

dependencies {
    compile('org.springframework.boot:spring-boot-starter-web')
    testCompile('org.springframework.boot:spring-boot-starter-test')

    // Spring Fox
    compile 'io.springfox:springfox-swagger2:2.2.2'
    compile 'io.springfox:springfox-swagger-ui:2.2.2'
    compile "com.google.guava:guava:17.0"
}

6行目から8行目に追加した3行がSpring Foxを使うために必要なものです。

続いてSpring Foxを使えるようにするための設定クラスを追加します。パッケージを右クリックしてAppConfig.javaを追加してください。

package com.example.hello;

import com.google.common.base.Predicate;
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 static com.google.common.base.Predicates.*;


@Configuration
@EnableSwagger2  // Springfoxを使うために必要なアノテーション
public class AppConfig {

    @Bean
    public Docket document() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select().paths(paths()).build().apiInfo(apiInfo());
    }


    private Predicate<String> paths() {
        return or(containsPattern("/*")); // エントリポイントを指定
    }

    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo("Greeting API", "This is Sample for Spring Fox.",
                "0.0.1", "", "", "", "");
        return apiInfo;
    }
}

これで導入は完了です。

実行

続いて実行してみましょう。IntelliJのTerminalを起動していつも通り下記のコマンドでOKです。

$ ./gradlew bootrun

前回までのチュートリアルであれば、表示するURLはhttp://localhost:8080/greetingでしたが、今回は下記のURLをブラウザで表示してみましょう。

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

上記のような画面が表示されているかと思います。

greeting-controllerという部分をクリックすることでRESTfulなエンドポイントが一覧で表示されるはずです。

続いてGETをクリックして開いてみましょう。パラメータやらレスポンスの種類などが表示されていますよね。いわゆるAPI仕様書が表示されているのです。すごく簡単ですよね。

では、早速Try it out!をクリックしてこのAPIを実行してみてください。前回のチュートリアルで確認した結果がResponse Bodyに表示されていれば成功です。Parametersに値を入れて実行してみても前回と同じ結果になっていますよね？

リクエストメソッドを制限する

ここまでの手順でAPIの仕様書とリクエストを実行できることがわかりましたが、GETやPSOTなど全てのリクエストメソッドが表示されていますよね？特定のリクエストメソッドに制限したい場合(というか製品としては当然そうですよね？笑)は、Javaのメソッドに宣言しているアノテーションを下記のようにするだけでSpring Foxのドキュメントも変更されます。

@GetMapping("/greeting")
public Greeting greeting(@RequestParam(value="name", defaultValue="World") String name) {
    return new Greeting(counter.incrementAndGet(),
            String.format(template, name));
}

上記の例であればGETメソッドのみリクエスト許可を行うようになります。これで再度実行してみてください。Spring Foxで生成されたドキュメントも下記のように変更されます。

まとめ

ドキュメントが整備されておらず、ソースコードと乖離がある状態ってよくあると思うんですが、今回ご紹介したようなライブラリを使うことで、API仕様書とソースコードの乖離をなくすことができますし、メンテにも手間がかかりません。それに、実行結果を確認することもできるようになります。

こういうものを上手く活用して本来時間をかけるべき部分にじっくりと時間をかけて良い開発ができればいいですね！

では今回はこの辺で。