[解決済み] Spring MVCアプリケーションにSwaggerを実装する「簡単な」方法

質問

私はシンプルなSpringで書かれたReSTFul APIを持っています（Spring Bootなし、派手なものなし！）。私はこれにSwaggerを実装する必要があります。これまでのところ、インターネット上のすべてのページは、混乱した設定と肥大化したコードで私を狂わせただけで、私はまったく移植性を見つけられませんでした。

誰か、これを達成するのに役立つサンプルプロジェクト（または詳細なステップのセット）を持っていますか？特に、私は swagger-springmvc を使用する良いサンプルを探しています。私はそれが「サンプル」を持っていることを知っていますが、せいぜい難解なコードは落胆させます。

私は、"なぜSwaggerが単にベストなのか"を探しているのではないことを明確にしなければなりません。私はSpring Bootなどを使用していません（そして、私の現在のタスクのために使用することはありません）。

どのように解決するのですか？

Springfox (Swagger 仕様 2.0、現在)

スプリングフォックス はSwagger-SpringMVCを置き換え、Swaggerの仕様1.2と2.0の両方をサポートするようになりました。 実装クラスが変更され、より深いカスタマイズが可能になりましたが、いくつかの作業が必要です。 その ドキュメント は改善されましたが、高度な設定のためにまだいくつかの詳細を追加する必要があります。 1.2 の実装に対する古い回答は、まだ以下で見つけることができます。

Maven への依存

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency> 

最小限の実装はほぼ同じに見えますが、ここで Docket クラスの代わりに SwaggerSpringMvcPlugin クラスの代わりに

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.regex("/api/.*"))
            .build()
            .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("TITLE")
            .description("DESCRIPTION")
            .version("VERSION")
            .termsOfServiceUrl("http://terms-of-services.url")
            .license("LICENSE")
            .licenseUrl("http://url-to-license.com")
            .build();
    }

}

Swagger 2.0 API ドキュメントが http://myapp/v2/api-docs .

Note : Spring bootを使用していない場合は、jackson-databindの依存関係を追加する必要があります。Springfoxはデータバインディングにjacksonを使用しているためです。

Swagger UIサポートを追加するのは、さらに簡単になりました。 Mavenを使用している場合、Swagger UI webjarのために以下の依存関係を追加します。

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

Spring Bootを使用している場合、Webアプリは自動的に必要なファイルをピックアップし、UIを http://myapp/swagger-ui.html (以前は http://myapp/springfox ). Spring Bootを使用していない場合は、下記の回答でyuriy-tumakhaさんが言及しているように、ファイルに対するリソースハンドラを登録する必要があります。 Javaの設定はこんな感じです。

@Configuration
@EnableWebMvc
public class WebAppConfig extends WebMvcConfigurerAdapter {

    @Override 
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

新しい 静的ドキュメント生成 機能もかなり良さそうです。私自身はまだ試していませんが。

Swagger-SpringMVC (Swagger仕様1.2以前)

のドキュメントは Swagger-SpringMVC のドキュメントは少しわかりにくいかもしれませんが、実際には驚くほど簡単に設定できます。 最も単純な設定では SpringSwaggerConfig ビーンを作成し、アノテーションベースの設定を有効にします (おそらく Spring MVC プロジェクトですでに行っていることでしょう)。

<mvc:annotation-driven/>
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />

しかし、Swagger のカスタム設定を定義するために SwaggerSpringMvcPlugin を使用することで、以前のXMLで定義されたビーンではなく、カスタムのSwagger設定を定義する余分なステップを踏む価値は十分にあると思います。

@Configuration
@EnableSwagger
@EnableWebMvc
public class SwaggerConfig {

    private SpringSwaggerConfig springSwaggerConfig;

    @SuppressWarnings("SpringJavaAutowiringInspection")
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
        this.springSwaggerConfig = springSwaggerConfig;
    }

    @Bean
    public SwaggerSpringMvcPlugin customImplementation(){

        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                .apiInfo(apiInfo())
                .includePatterns(".*api.*"); // assuming the API lives at something like http://myapp/api
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("TITLE")
            .description("DESCRIPTION")
            .version("VERSION")
            .termsOfServiceUrl("http://terms-of-services.url")
            .license("LICENSE")
            .licenseUrl("http://url-to-license.com")
            .build();
    }

}

アプリケーションを実行すると、API仕様が http://myapp/api-docs . 派手なSwagger UIをセットアップするために、静的ファイルを GitHub プロジェクト から静的ファイルをクローンして、プロジェクトに配置する必要があります。 プロジェクトが静的なHTMLファイルを提供するように設定されていることを確認してください。

<mvc:resources mapping="*.html" location="/" />

次に index.html ファイルをSwagger UIの最上位にある dist ディレクトリにあります。 ファイルの最上部には、いくつかのJavaScriptが表示されます。 api-docs のURLを参照するJavaScriptがあります。 これを編集して、自分のプロジェクトのSwaggerドキュメントを指すようにします。

  if (url && url.length > 1) {
    url = url[1];
  } else {
    url = "http://myapp/api-docs";
  }

これで http://myapp/path/to/swagger/index.html に移動すると、プロジェクトのSwagger UIインスタンスが表示されるはずです。