【问题标题】:Jersey + Swagger + Swagger-UI + Maven configurationJersey + Swagger + Swagger-UI + Maven 配置
【发布时间】:2016-07-31 21:09:55
【问题描述】:

我第一次尝试使用 Jersey 和 Maven 招摇,我想知道我是否走在正确的道路上。我有 jersey、maven 和 swagger 在我的本地计算机上工作。很快,我想将它部署到不同的环境并包含 swagger-ui。

  1. 如果我将 web.xml 文件配置为 <param-value>http://localhost:8080/api</param-value>,那么我看到 swagger 在我的本地计算机上工作。但是每次我想将我的代码部署到不同的环境(例如从开发环境到 QA 环境,再到生产环境)时,我是否需要更改这个地址,如果是这样,我将如何去做?不可能/不是招摇的意思吗?

  2. 我想将 swagger-ui 合并到我的项目中。我看到在线建议从 git 手动下载文件并将其放入我的项目中。但我想知道是否有一个我可以使用的 maven 依赖项,以便我可以使用 maven 获取必要的代码来使用 swagger-ui 并将其配置为与 jersey 一起使用。如果是,那么依赖是什么?如何使用它来通过多个环境部署代码?

如果可能的话,请提供指导和教程链接,因为我是这项技术的新手。另外,如果我在使用 jersey/swagger/swagger-ui/maven 的思维过程中没有从 git 手动下载代码并能够通过多个环境部署代码,请告诉我,以便我可以寻找另一种使用方式REST 在我的应用程序中。

感谢您的帮助。

pom.xml:

    <repositories>
      <repository>
          <id>maven2-repository.java.net</id>
          <name>Java.net Repository for Maven</name>
          <url>http://download.java.net/maven/2/</url>
          <layout>default</layout>
      </repository>
  </repositories>

  <properties>
      <jersey2.version>2.19</jersey2.version>
      <jaxrs.version>2.0.1</jaxrs.version>
  </properties>

  <!-- Dependencies -->
  <dependencies>


    <!-- JAX-RS -->
    <dependency>
        <groupId>javax.ws.rs</groupId>
        <artifactId>javax.ws.rs-api</artifactId>
        <version>${jaxrs.version}</version>
    </dependency>
    <!-- Jersey 2.19 -->
    <dependency>
        <groupId>org.glassfish.jersey.containers</groupId>
        <artifactId>jersey-container-servlet</artifactId>
        <version>${jersey2.version}</version>
    </dependency>
    <dependency>
        <groupId>org.glassfish.jersey.core</groupId>
        <artifactId>jersey-server</artifactId>
        <version>${jersey2.version}</version>
    </dependency>
    <dependency>
        <groupId>org.glassfish.jersey.core</groupId>
        <artifactId>jersey-client</artifactId>
        <version>${jersey2.version}</version>
    </dependency>

     <!-- Servlet Library -->
     <!-- http://mvnrepository.com/artifact/javax.servlet/javax.servlet-api -->
     <dependency>
         <groupId>javax.servlet</groupId>
         <artifactId>javax.servlet-api</artifactId>
         <version>3.1.0</version>
         <scope>provided</scope>
     </dependency>

     <!-- Spring dependencies -->
     <!-- http://mvnrepository.com/artifact/org.springframework/spring-core -->
     <dependency>
         <groupId>org.springframework</groupId>
         <artifactId>spring-core</artifactId>
         <version>4.1.4.RELEASE</version>
     </dependency>

     <!-- http://mvnrepository.com/artifact/org.springframework/spring-web -->
     <dependency>
         <groupId>org.springframework</groupId>
         <artifactId>spring-web</artifactId>
         <version>4.1.4.RELEASE</version>
     </dependency>

     <!-- http://mvnrepository.com/artifact/org.springframework/spring-webmvc -->
     <dependency>
         <groupId>org.springframework</groupId>
         <artifactId>spring-webmvc</artifactId>
         <version>4.1.4.RELEASE</version>
     </dependency>

    <!-- Junit -->
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-jersey2-jaxrs</artifactId>
        <version>1.5.0</version>
    </dependency>
  </dependencies>

web.xml

    <?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
  id="WebApp_ID" version="3.0">

  <display-name>HelloWorldSpring</display-name>

  <servlet>
      <servlet-name>spring-mvc</servlet-name>
      <servlet-class>
          org.springframework.web.servlet.DispatcherServlet
      </servlet-class>
      <load-on-startup>1</load-on-startup>
  </servlet>    

  <servlet-mapping>
      <servlet-name>spring-mvc</servlet-name>
      <url-pattern>/</url-pattern>
  </servlet-mapping>

  <servlet>
      <servlet-name>jersey-serlvet</servlet-name>
      <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
      <init-param>
           <param-name>jersey.config.server.provider.packages</param-name>
           <param-value>
           io.swagger.jaxrs.listing, 
           com.jer.rest
           </param-value>
      </init-param>
      <load-on-startup>1</load-on-startup>
  </servlet>

  <servlet-mapping>
      <servlet-name>jersey-serlvet</servlet-name>
      <url-pattern>/rest/*</url-pattern>
  </servlet-mapping>


   <servlet>
      <servlet-name>Jersey2Config</servlet-name>
      <servlet-class>io.swagger.jersey.config.JerseyJaxrsConfig</servlet-class>
      <init-param>
          <param-name>api.version</param-name>
          <param-value>1.0.0</param-value>
      </init-param>
      <init-param>
          <param-name>swagger.api.basepath</param-name>
          <param-value>http://localhost:8080/HealthTracker/rest</param-value>
      </init-param>
      <load-on-startup>2</load-on-startup>
  </servlet>

   <!-- Other XML Configuration -->
  <!-- Load by Spring ContextLoaderListener -->
  <context-param>
      <param-name>contextConfigLocation</param-name>
      <param-value>/WEB-INF/root-context.xml</param-value>
  </context-param>


   <!-- Spring ContextLoaderListener -->
  <listener>
      <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
  </listener>

</web-app>

【问题讨论】:

    标签: eclipse maven jersey swagger swagger-ui


    【解决方案1】:

    以下是我认为可以回答您的问题的内容:

    1. 为了能够根据不同的环境配置 swagger,那么这些是您可以遵循的步骤:

      i) 创建一个 Bootstrap 类来配置 swagger bean(参考:https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-2.X-Project-Setup-1.5Setting the Api Version with Swagger UI

      ii) 使用属性文件中的值设置上述 bean 中的值,您可以在任何环境中轻松地在代码之外进行配置。

    2. Swagger dist 由 html/css/image/js 文件组成。它不能作为 Maven jar 依赖项添加。

    希望这会有所帮助!

    【讨论】:

      【解决方案2】:

      这里有一个带有 java doclet 的解决方案(不需要大张旗鼓的注释)。使用maven-javadoc-plugin 并将swagger-doclet 配置为alternate doclet。使用maven profiles 可以管理不同的环境:

      <profile>
          <id>dev</id>
          <build>
              <plugins>
                  <plugin>
                      <groupId>org.apache.maven.plugins</groupId>
                      <artifactId>maven-javadoc-plugin</artifactId>
                      <version>2.9.1</version>
                      <executions>
                          <execution>
                              <id>generate-service-docs</id>
                              <phase>generate-resources</phase>
                              <configuration>
                                  <doclet>com.carma.swagger.doclet.ServiceDoclet</doclet>
                                  <docletArtifact>
                                      <groupId>com.carma</groupId>
                                      <artifactId>swagger-doclet</artifactId>
                                      <version>1.0.3</version>
                                  </docletArtifact>
                                  <reportOutputDirectory>${project.build.outputDirectory}</reportOutputDirectory>
                                  <useStandardDocletOptions>false</useStandardDocletOptions>
                                  <additionalparam>-apiVersion 1 -docBasePath
                                      https://example.com/apidocs -apiBasePath
                                      https://example.com/api -swaggerUiPath
                                      ../../../src/main/resources/swagger-ui/
                                  </additionalparam>
                              </configuration>
                              <goals>
                                  <goal>javadoc</goal>
                              </goals>
                          </execution>
                      </executions>
                  </plugin>
              </plugins>
          </build>
      </profile>
      

      我将swagger资源直接放入我的项目中。所以自定义css和html很容易。

      或者,如果您不想将 swagger 放入您的存储库,您可以使用 frotend-maven-pluginbower 来管理您的 js/css 依赖项(例如:swagger-ui)。

      我直接从嵌入式服务器提供 swagger 作为静态资源(在我的例子中,我使用了 grizzly):

      String apiDocs = Env.getApiDocs();         
      server.getServerConfiguration().addHttpHandler(
          new CLStaticHttpHandler(GrizzlyStarter.class.getClassLoader(), apiDocs), apiDocs);
      

      【讨论】:

        【解决方案3】:

        查看链接https://github.com/swagger-api/swagger-samples/tree/2.0/java

        它有关于如何在您的项目中配置 Swagger 3.0 的优秀示例(参见 java-jersey2-webxml 示例)。对于早期版本,请检查分支

        就用户界面而言,你可以下载所需的文件,或者你可以在 pom.xml 中添加以下依赖项。

        <dependency>
            <groupId>org.webjars</groupId>
            <artifactId>swagger-ui</artifactId>
            <version>3.6.1</version>
        </dependency>
        

        它将下载必要的 ui 文件。您可以将下载的 index.html 复制到您的项目中并编辑 url。

        【讨论】:

          【解决方案4】:

          我遇到了同样的问题并创建了一个库,如果将其包含到 Jersey 项目中,它将添加 swagger 3.0 UI。请看一下codeblog post 想法是所有swagger UI 静态内容都与库一起打包并在运行时提取。此外,库将负责为 swagger UI 创建 Web 上下文并调整对 openapi.json 文件的引用。您需要将 2 个属性和此代码添加到您的项目中:

          SwaggerContext.addSwaggerServlet(tomcat, context,
              ConfigBuilder.builder(ConfigType.TYPE_SAFE)
                      .build()
                      .getConfig("swagger"),
              EmailApplication.class);
          

          和属性:

          swagger.package="com.itzap"
          swagger.apiBaseUrl="http://{application url}"
          

          如果所有其他配置保留默认设置,则可以通过此 URL 访问 swagger UI:

          http://{application base URL}/api/v1/swagger 
          

          【讨论】: