Swagger UIでAPIドキュメント作成を自動化する

今更言うまでもないことかもしれませんが、「後の保守する人のことを考えて開発する」というのは重要です。

コードをきれいに書くことはもちろんですが、適切なドキュメントを適切な量作成し、それをメンテナンスしていくことも必要です。

とはいっても、開発者の本音としてはコードを書くことに集中したいですよね。

とくにアジャイル開発が隆盛を誇っている今、APIドキュメントなどを開発途中に書いても、仕様の変更に伴って書き直しをしなければならなくなり（ダブルメンテ）、結局最後には「アテにならない仕様書」が残る。。。という話はよく聞きます。

そこで、APIドキュメントの作成・メンテナンスを自動化したい、と思うのは自然な発想です。

今回は、Swaggerを使ってAPIドキュメント作成を自動化してみました。（ちなみに現在仕事で進行中のプロジェクトにも導入しました！ドキュメントメンテコストが下がってだいぶ楽になりました。）

今回は、Spring Bootに導入する例を紹介します。

手順１.gradleの依存関係にSwagger関連のライブラリを追加

Spring Bootで使用する場合は、SpringFoxというラッパーライブラリを使います。

dependencies {
    // product libraries...

    // https://mvnrepository.com/artifact/io.springfox/springfox-swagger2
    compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.5.0
    // https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
    compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.5.0'

    // test libraries...
}

手順2.Swagger関連の設定をBeanに記述する

Swagger関連の設定Beanを作成します。


@Configuration
@EnableSwagger2
public class SwaggerConfig {

  @Bean
  public Docket documentation() {
    return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.regex("/api.*")).build().pathMapping("/")
        .directModelSubstitute(Timestamp.class, Long.class).apiInfo(metadata());　//Timestampクラスを、UNIXタイムのLong値で表示する
  }

  @Bean
  public UiConfiguration uiConfig() {
    return UiConfiguration.DEFAULT; //swaggerのUIの設定
  }

  private ApiInfo metadata() {
    return new ApiInfoBuilder().title("Awesome API").version("1.0").build();
  }

}

手順3.アノテーションベースでドキュメントの内容を記述

Controllerにアノテーションでドキュメントを記述します。



@Api(tags = { "タグを記述" }) //swaggerのドキュメンテーション用アノテーション
@RequestMapping("/api")
@RestController
public class AwesomeController {

  @Autowired
  private AwesomeServiceSpec awesomeService;

  //@ApiOperationに、このAPIの内容を記述
  @ApiOperation(value = "一件取得", notes = "オブジェクト一件の情報を取得します。")
  @RequestMapping(value = "/one", method = RequestMethod.GET)
  public Awesome one(@RequestParam("id") String id) {
    return awesomeService.findOne(id);
  }

  @ApiOperation(value = "一覧取得", notes = "検索クエリに一致するオブジェクトの一覧を取得します。")
  @RequestMapping(value = "/list", method = RequestMethod.GET)
  public List<Awesome> list(@RequestParam("query") String query) {
    return awesomeService.search(query);
  }

}

尚、戻り値の構造、必要とするリクエストパラメータの構造などは、ある程度自動で作成してくれます。

開発途中によくあるリクエストパラメータや戻り値の微妙な変更等に対して、いちいちドキュメントを書きなおさなくていいのは大きなメリットですね。
こだわりたい場合は、model層に同様にSwaggerアノテーションを付与してドキュメント化します。
詳しくは、SpringFoxのドキュメントを参考にしてください。