web-dev-qa-db-ja.com

Mavenでswagger-uiを構成する

JAX-RS RESTプロジェクトをSwaggerと統合しています。多くのドキュメントとチュートリアルを読みました。私のお気に入りの図は次のとおりです（ Philipp Hauerのブログ に感謝）：

enter image description here

その画像は、Swaggerがどのように機能するかを理解するのに大いに役立ちました。

Swaggerがどのように機能するかを学んだ後、pom.xmlを変更しました。

プロジェクトにswagger-jersey2-jaxrs依存関係を追加しました。これにより、説明されているSwagger関連のアノテーションを使用できるようになります ここ ：

<!-- for Swagger-Core Annotations -->
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-jersey2-jaxrs</artifactId>
    <version>1.5.13</version>
</dependency>

重要：guavaライブラリがこの依存関係に属しているため、最新の1.15.18 swagger-jersey2-jaxrs依存関係を使用できません。これにより、クラスローダーに重大な問題が発生しました。最新（v5.181）で Payara appserver：

  Exception Occurred :Error occurred during deployment: Exception while loading the app : Java.lang.IllegalStateException: ContainerBase.addChild: start: org.Apache.catalina.LifecycleException: org.Apache.catalina.LifecycleException: Java.lang.NoSuchMethodError: com.google.common.collect.Sets$SetView.iterator()Lcom/google/common/collect/UnmodifiableIterator;. Please see server.log for more details. ]]

とにかく、次のプラグインも私のpom.xmlに追加しました。これは、swagger-uiパーツをダウンロードし、mavenターゲットフォルダーに解凍します。

<plugin>
    <groupId>com.googlecode.maven-download-plugin</groupId>
    <artifactId>download-maven-plugin</artifactId>
    <version>1.4.0</version>
    <executions>
        <execution>
            <id>swagger-ui</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>wget</goal>
            </goals>
            <configuration>
                <url>https://github.com/swagger-api/swagger-ui/archive/v${version.swagger-ui}.tar.gz</url>
                <unpack>true</unpack>
                <outputDirectory>${project.build.directory}</outputDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>

ここでの私の問題は、プロキシサーバーの背後にいるため、HTTPSプロキシ構成をmavensetting.xmlに追加する必要があることでした。

最後に、pom.xmlにmaven-war-pluginを追加しました。これにより、swagger-ui関連の静的ファイルが最終的なwarファイルにコピーされます。

<plugin>
    <groupId>org.Apache.maven.plugins</groupId>
    <artifactId>maven-war-plugin</artifactId>
    <version>3.2.0</version>
    <configuration>
        <warName>${project.build.finalName}</warName>
        <webappDirectory>${basedir}/target/${project.build.finalName}</webappDirectory>
        <webResources>
            <webResource>
                <directory>${project.build.directory}/swagger-ui-${version.swagger-ui}/dist</directory>
                <targetPath>swagger</targetPath>
            </webResource>
        </webResources>
    </configuration>
</plugin>

次のコードでSwaggerドキュメントジェネレータを初期化します。

@ApplicationPath("api")
public class Configurator extends Application {
    public Configurator() {
        BeanConfig beanConfig = new BeanConfig();
        beanConfig.setVersion("1.0.0");
        beanConfig.setSchemes(new String[]{"http"});
        beanConfig.setHost("localhost:8080");
        beanConfig.setBasePath("my-rest-1.0.0/api");
        beanConfig.setResourcePackage(EchoRest.class.getPackage().getName());
        beanConfig.setTitle("JAX-RS + Swagger and Swagger UI Example");
        beanConfig.setDescription("Sample RESTful API built using JAX-RS, Swagger and Swagger UI");
        beanConfig.setScan(true);
    }
}

正常に動作します。 http：// localhost：8080/my-rest-1.2.0/api/swagger.json は、適切なSwaggerドキュメントとともに返されます。

[〜＃〜]しかし[〜＃〜]

  1. swagger/index.htmlファイルのJavaScript部分にあるハードコードされたURL値をデフォルトの http://petstore.swagger.io/v2/swagger.json から自分のURLに上書きする必要があります。 mavenプラグインを介してswagger-uiを自動的にダウンロードしてコピーしますが、mavenでのコンパイル中にURL変数の値を自動的に変更する方法がわかりません。
  2. 私のWARファイルの名前は、mavenpom.xmlで使用されているバージョン情報によって異なります。つまり、Configuratorクラスで使用されるハードコードされたバージョン、ホスト、およびベースパスは、しばらくすると正しくなりません。アプリケーションのルートURLと@ApplicationPath（ "api"）アノテーションの値に基づいて、この値を自動的に生成できますか？
javajax-rsswaggerswagger-uiswagger-2.0
5
zappee

特にあなたのニーズの1つを指摘するために、ハードコードされたURLを置き換えるためにMavenのreplacer-pluginを使用しています。

<!-- replace name of the specification file to show-->
            <plugin>
                <groupId>com.google.code.maven-replacer-plugin</groupId>
                <artifactId>replacer</artifactId>
                <executions>
                    <execution>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>replace</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <file>${project.build.directory}/swagger-ui/META-INF/resources/webjars/swagger-ui/${swagger-ui.version}/index.html</file>
                    <replacements>
                        <replacement>
                            <token>"https://petstore.swagger.io/v2/swagger.json"</token>
                            <value>location.protocol + '//' + location.hostname+':'+location.port+'/${project.artifactId}-${project.version}/Your-URL/openapi.json'</value>
                        </replacement>
                    </replacements>
                </configuration>
            </plugin>
1
noltedx