SpringfoxでGET APIのドキュメント設定

利用バージョン：Springfox2.9.2

Spring Boot 2で簡単に作ったGETのAPIに、ほとんど設定なしでswaggeruiを表示してみたら以下のようになりました。

表示を改善する際の設定メモです。

ドキュメントのタイトルとバージョン番号

画像で「Api Documentation 1.0」と書いてある部分を変更します。

タイトルは「テストAPI」、バージョン番号はとりあえず0.0.1くらいに。

動作確認用なので、ライセンスなどは空で設定しました。

Swagger表示用に用意した@ConfigurationのクラスでDocket構築後に、.apiInfoメソッドにApiInfoオブジェクトを渡すことで設定できました。

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
        .select()
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build()
        .apiInfo(getApiInfo());
  }
  
  private ApiInfo getApiInfo() {
    return new ApiInfo("テストAPI", "説明", "0.0.1", "", 
        new Contact("", "", ""), "", "", Collections.emptyList());
  }
}

basic-error-controllerを非表示にする

ApiSelectorBuilder.apisに渡すパラメータが原因ですね。作成したパッケージだけに絞ります。

上のapi()メソッド中の.apis()を以下のように変更。渡しているパラメータはパッケージ名です。

        .apis(RequestHandlerSelectors.basePackage("biz.house_soft.positiondata"))

同時にModelsの下にあった自分で追加したわけではないModelAndView, Viewも非表示になってます。

コントローラーの表示を変更

@RestControllerをつけたおいたクラス名がほとんどそのままでているので、これを変更します。

名前とその右に表示される説明を設定するにはControllerに@Apiアノテーションをつけるのですが、説明に対応するdescriptionが@Deprecatedにマークされているのに気づきました。

代替策として推奨されていたのが、tagsをつけておいて、Docketで設定する方法。

まずControllerを

@RestController
@Api(tags = "位置情報")
public class PointDataController {

のようにtagsをつけて(この時点でControllerの名前はtagsの値に変わる)、Docketのbuild()後に、

@Bean
public Docket api() {
  return new Docket(DocumentationType.SWAGGER_2)
      .select()
      .apis(RequestHandlerSelectors.basePackage("biz.house_soft.positiondata"))
      .paths(PathSelectors.any())
      .build()
      .apiInfo(getApiInfo())
      .tags(new Tag("位置情報", "位置情報の説明"));
}

と.tagsにTagオブジェクトを渡してやるとその第2引数のdescriptionがコントローラーの右隣に表示されるようになりました。

コントローラー内の各メソッドの右側にメソッド名がそのままでていますが、これはメソッドのアノテーションに@ApiOperation(value=”位置情報全件取得”)を指定すると、valueの値が表示されます。

ここまでやるとこんな感じになりました。