用maven配置swagger-ui

Question

我正在将我的JAX-RS REST项目与Swagger集成。我阅读了很多文档和教程，我最喜欢的数字如下（感谢Philipp Hauer's blog）：

这个形象帮助我理解了Swagger的工作原理。

在我学会了Swagger如何工作后，我修改了我的pom.xml。

我在项目中添加了swagger-jersey2-jaxrs依赖项，这使我能够使用描述here的swagger相关注释：

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

重要提示：我无法使用最新的1.15.18 swagger-jersey2-jaxrs依赖项，因为guava库属于此依赖项，使用最新的（v5.181）Payara应用程序服务器产生严重的类加载器问题：

  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代理配置添加到maven setting.xml。

最后，我将maven-war-plugin添加到pom.xml，它将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返回一个适当的招摇文档。

但

1. 我需要将swagger/index.html文件的JavaScript部分中的硬编码url值从默认的http://petstore.swagger.io/v2/swagger.json覆盖到我的URL。我自动通过maven插件下载并复制swagger-ui，但我不知道在使用maven编译时如何自动更改URL变量的值。
2. 我的WAR文件的名称取决于maven pom.xml中使用的版本信息。这意味着Configurator类中使用的硬编码版本，主机和基本路径在一段时间后不会正确。我可以根据应用程序根URL和@ApplicationPath（“api”）注释中的值自动生成此值吗？

Answer 1

特别是为了满足您的需求，我们在maven中使用replacer-plugin来替换硬编码的url：

<!-- 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>