Spring Fox ①導入編

Spring Fox とは

Springフレームワークと組み合わせて使うことで対象システムのAPIドキュメントを自動生成してくれる。
※内部的には後述のSwaggerを利用している。

また、システムから自動生成することでヒューマンミスを抑えて統一性のあるドキュメントにすることが可能です。

Swaggerとは

要点が多いので箇条書きで・・・。φ(。。)

Swagger Specという定義ファイルで管理
JSON or YAMLで定義
Swagger Specを基にSwagger UIがドキュメント化する
生成ドキュメントはHTMLとjQueryベースでカスタマイズも可能
さまざまな言語のフレームワークに対応
Swagger Specを作らずSwagger coreを用いてrのように作成可能することも可能
他にもSwagger EditorやSwagger Codegen、Swagger Node等のツールもある(らしい)
Postman、Amazon API Gateway等の外部ツールも対応をしている
Swagger Test Templateを使うとSpecファイルからJavaScriptのテストコードを自動生成して実行してくれる
RESTful APIのインターフェイスを記述するための標準フォーマットを推進する団体「Open API Initiative」がSwaggerを採用している

※他のAPIドキュメント生成ツールとしては、API blueprintが有名

　導入

1. 依存関係の追加

gradleの依存関係に追加

build.gradle

dependencies {
...
  compile "io.springfox:springfox-swagger2:2.2.2"
  compile "io.springfox:springfox-swagger-ui:2.2.2"
  compile "com.google.guava:guava:17.0"
...
}

2. Spring Foxの有効化

アノテーションを追加し、有効にする

Application.java

@SpringBootApplication
@EnableSwagger2//追加
public class Application extends SpringBootServletInitializer
{
    public static void main( String... args )
    {
         SpringApplication.run( Application.class, args );
    }
}

3. ドキュメント用のJavaConfigを追加

SwaggerConfiguration.java

@Configuration
public class SwaggerConfiguration
{
    @Bean
    public Docket publicDocument()
    {
        return new Docket( DocumentationType.SWAGGER_2 ).groupName( "public" )
                .select()
                .paths( paths() )
                .build()
                .apiInfo( apiInfo() );
    }

    private ApiInfo apiInfo()
    {
        ApiInfo apiInfo = new ApiInfo(
                "My REST API",
                "Some custom description of API.",
                "API TOS",
                "Terms of service",
                "myeaddress@company.com",
                "License of API",
                "API license URL");
        return apiInfo;
    }

    private Predicate<String> paths() {
        return or(
           regex("/some/endpoint")
        );
    }

}

4. 動作確認

/swagger-ui.htmlにアクセス
※自動でエンドポイントが追加されています。

戻り値のJavaクラスが自動でJSON　SCHEMAに変換されていたり、この画面からリクエストを投げることができるので便利。

次回

次は

ヘッダーパラメータの追加方法
DB値を使ったプルダウン化
静的ドキュメント化

あたりでも触れるつもりです。

じゃあの。