こんにちは!ぐち(@bloguchi)です。
前回ご紹介したSpring bootで作るRESTfulなAPIのドキュメントを自動で生成してくれる便利なライブラリをご紹介します。
前回の記事はこちらからどうぞ。
Swagger
Web APIのドキュメントとブラウザからリクエストを実行できるようなページを生成してくれるライブラリがあります。Swagger
というものですが、それをSpringと合わせて使えるようにしたのがSpring Fox
(と認識しています。笑)です。
Swaggerに関しては公式サイトを見てください。
Spring Foxのサイトはこちらです。
プロジェクトに導入
では、早速プロジェクトに導入しましょう。前回チュートリアルで作成したプロジェクトに追加していきましょう。
まずは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仕様書とソースコードの乖離をなくすことができますし、メンテにも手間がかかりません。それに、実行結果を確認することもできるようになります。
こういうものを上手く活用して本来時間をかけるべき部分にじっくりと時間をかけて良い開発ができればいいですね!
では今回はこの辺で。