Spring BootとSwagger UIでAPIの楽ちんドキュメント化

2017年7月10日

エンジニアの谷本です。
某社さんにてSpring Bootを使って社内向けのWeb APIの開発を行っています。
Web APIを利用してtoCのプロダクトを開発するチームが別にあり、そちらとAPI仕様について連携する必要がありSwagger UIを利用しています。

ドキュメントを作るのはよいのですがおっちょこちょいの私にとってはソースからドキュメントファイルへ記載するさいにtypoや転記ミスが多く、実装を修正/変更した場合にもれなく更新するのに集中力が取られるのが辛い時がありました。
開発時に使ってもらう開発環境のサーバーへのアクセスやリクエストのパラメータについて逐一説明するのも大変で、チャットだと長くなってしまったり流れてしまうので統一され分かりやすいフォーマットでドキュメント化できないかと思案していました。

そんな中、Spring Boot+Swagger UIはアノテーション追加+ちょい実装でAPIのドキュメント化ができ、アノテーションを使うSpringの流儀に則っていたため簡単かつ楽ちんだったので紹介したいと思います。

Swaggerとは

RESTfulなAPIの仕様をブラウザで参照できるドキュメントにしてくれるフレームワークです。
Springの流儀に従ってRESTfulなAPIになっていれば、アノテーションをちょいちょい追加してやるとブラウザで確認できるいいかんじのドキュメントができます。

Swaggerのメリット

Swaggerを利用する以前はMarkdownでAPI仕様書を記述し、htmlに変換してからPDFに出力し、必要なチームに送るなど手間がかかっていました。
Swagger(Swagger UI)を利用し始めてからは仕様を確認できる開発環境のSwagger UIのURLを共有し、変更点のみ連絡したりするだけでよくなり仕様ドキュメントの運用が楽になりました。
また、メソッドの引数、返却値、アノテーションのパラメータを元にドキュメントにしているので、単純な記述ミスや転記ミスがなくなったのでドキュメントとしての質もあがりました。
  • デザインや記述内容が統一されたフォーマットになる
    • デフォルトのデザインでもいいかんじ
  • ブラウザ上でAPIの仕様が確認できるページが自動で生成される
    • 自動生成のためヒューマンエラーが入り込みづらい
  • ブラウザ上で試すことが出来る仕組みも生成されるので説明を事細かにドキュメント化せずともエンジニアであれば理解しやすい
  • メソッドのアノテーションから仕様を生成してくれる
    • コードとドキュメントの距離が近くなる
    • ドキュメント用のアノテーションを含めてバージョン管理に含めることができる

デメリット

楽ちんといえでも多少のメンテナンスコストが必要になります。SpringのControllerはアノテーションを多用する場面も多く、ドキュメントのためにアノテーションが増えるのは見通しが悪くかんじるのはデメリットといえるかもしれません。
  • アノテーションが増える
  • 本番環境では見えなくする工夫が必要な場合もある
  • コード中に記述するコメント程ではないがメンテナンスする必要はある

実装方法

今回はSpring BootでWebアプリを作成しSwagger UIで表示するまでのサンプルを作成します。WebアプリはMavenでビルドします。
(サンプルコードはコチラ

基本的にドキュメントにしたいメソッドにSwaggerのアノテーションを追加する形になります。取っ掛かりやはじめの雰囲気はサンプルコードを見て頂き、詳細に使う場合には公式ドキュメントを見ながら少しづつ追加していくと心折れずにドキュメントが充実していくと思います。

1. Spring BootでWebアプリを構築した上で、Swagger UIで必要なライブラリをpom.xmlに追記します。

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

2. Swagger UIを出力してくれるBeanの設定を追記します。()

  @Configuration
  @EnableSwagger2
  protected static class SwaggerConfig {
    @Bean
    Docket swaggerSpringMvcPlugin() {
      return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo() {
      return new ApiInfoBuilder()
          .title("Swagger Example")
          .build();
    }
  }

3. ControllerクラスのメソッドにSwaggerのアノテーションを追加します()
4. mvnコマンドの

mvn spring-boot:run

でWebアプリを起動し、ブラウザで http://localhost:8080/swagger-ui.html にアクセスするとAPIの仕様が確認できます。

まとめ

本番コードと同じファイルにアノテーションを追加してドキュメント化することでメンテナンス漏れ/ドキュメントの陳腐化を防ぎやすく、リクエスト/レスポンスの内容はコードから読み取って自動生成してくれるので簡単かつ手作業による間違いが少ないのが良いと思います。レガシーソフトウェア改善ガイドにもあるように、コードとドキュメントの置き場が近いというのは間違いなくグッドプラクティスだなと実感しました。
ブラウザからすぐに試すことができるフォームもいいかんじにgoodで、エラーの問い合わせ時に自分で使って試してみたりしています。
API仕様をパブリックに公開しなくても網羅的に見れるのは設計時やチームで議論する際に役立ちます。
APIのドキュメント化にSwagger UIを是非とも導入してみてはいかがでしょうか。

参考URL