使用 maven 配置 swagger-ui

Question

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

这张图片对我理解 Swagger 的工作原理很有帮助。

在了解 Swagger 的工作原理后，我修改了我的 pom.xml。

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

<!-- 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 相关的静态文件复制到我的最终战争文件中：

<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 中的替换插件来替换硬编码的 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>