web-dev-qa-db-ja.com

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

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

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

「なぜSwaggerが最高なのか」を探しているのではないことを明確にしなければなりません。私はSpring Bootなどを使用していません（現在のタスクでは使用しません）。

springspring-mvcswagger
80
wavicle

Springfox（Swagger spec 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.0 APIドキュメントがhttp://myapp/v2/api-docsで利用可能になります。

注：Springブートを使用していない場合は、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アプリは必要なファイルを自動的に取得し、http://myapp/swagger-ui.html（以前：http://myapp/springfox）にUIを表示します。 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 spec 1.2、より古い）

Swagger-SpringMVC のドキュメントは少しわかりにくいかもしれませんが、実際には設定が非常に簡単です。最も単純な構成では、SpringSwaggerConfig Beanを作成し、注釈ベースの構成を有効にする必要があります（おそらく、Spring MVCプロジェクトで既に実行しています）。

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

ただし、以前のXML定義のBeanの代わりにSwaggerSpringMvcPluginを使用して、カスタム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();
    }

}

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

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

次に、Swagger UI distディレクトリの最上位にあるindex.htmlファイルを編集します。ファイルの先頭に向かって、別のプロジェクトの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インスタンスが表示されます。

117
woemler

WebJar依存関係とリソースマッピングを追加した後、Springfox Swagger UIが機能します。 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/"/>

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

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

 @EnableSwagger2
 public class SwaggerConfiguration {
 }
12
Yuriy Tumakha

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

このリポジトリでSpring MVCアノテーションを使用した作業プラグインの簡単なサンプルを確認してください：

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

またはJAX-RSの場合

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

1
kkhipis