SpringMVCアプリケーションにSwaggerを実装するための「簡単な」方法

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

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

「Swaggerが単に最高である理由」を探しているのではないことを明確にする必要があります。Spring Bootなどを使用していません（現在のタスクでは使用しません）。

Springfox（Swagger仕様2.0、現在）

Springfoxは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.0APIドキュメントがで利用できるようになりますhttp://myapp/v2/api-docs。

注：Springブートを使用していない場合は、jackson-databind依存関係を追加する必要があります。springfoxはデータバインディングにjacksonを使用するため。

SwaggerUIサポートの追加がさらに簡単になりました。Mavenを使用している場合は、Swagger UIWebjarに次の依存関係を追加します。

<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のドキュメントは少し混乱する可能性がありますが、実際には非常に簡単にセットアップできます。最も単純な構成では、SpringSwaggerConfigBeanを作成し、アノテーションベースの構成を有効にする必要があります（これはおそらくSpring MVCプロジェクトですでに行っています）。

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

ただし、SwaggerSpringMvcPlugin以前のXML定義のBeanの代わりに、を使用してカスタム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ます。派手なSwaggerUIをセットアップするには、GitHubプロジェクトから静的ファイルのクローンを作成してプロジェクトに配置する必要があります。プロジェクトが静的HTMLファイルを提供するように構成されていることを確認してください。

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

次にindex.html、SwaggerUIdistディレクトリのトップレベルでファイルを編集します。ファイルの先頭に、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、プロジェクトのSwaggerUIインスタンスが表示されます。

Springfox Swagger UIは、WebJarの依存関係とリソースマッピングを追加した後に機能します。 http://www.webjars.org/documentation#springmvc

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.2.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.2.2</version>
    </dependency>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>bootstrap</artifactId>
        <version>3.3.5</version>
    </dependency>

spring-servlet.xml：

<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

またはSpringAnnotation https://github.com/springfox/springfox-demos/blob/master/spring-java-swagger/src/main/java/springfoxdemo/java/swagger/SpringConfig.java

Swagger2を有効にする必要があります

 @EnableSwagger2
 public class SwaggerConfiguration {
 }

swagger-maven-pluginを使用してswagger.jsonを生成し、それを静的なswagger-uiにコピーすることも検討できます。

このリポジトリでSpringMVCアノテーションを使用して動作するプラグインの簡単なサンプルを確認してください。

https://github.com/khipis/swagger-maven-example

またはJAX-RSの場合

https://github.com/kongchen/swagger-maven-example