如何集成Swagger與Maven + Java + Jersey + Tomcat

Question

我似乎無法理解如何集成Swagger來生成API文檔。 url：####：8080/MyService/rest/users/getall
我已將註釋添加到代碼和依賴項中。
我嘗試訪問：####：8080/MyService/rest /但表示未找到它。

//web.xml

 <servlet> 
    <servlet-name>mycompany-users-serlvet</servlet-name> 
    <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class> 
    <init-param> 
     <param-name>com.sun.jersey.config.property.packages</param-name> 
     <param-value>com.users.services.mycompany,com.wordnik.swagger.jersey.listing</param-value> 
    </init-param> ` 
    <servlet> 
    <servlet-name>JerseyJaxrsConfig</servlet-name> 
    <servlet-class>com.wordnik.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>####:8080/MyService/rest/</param-value> //not sure What this should be? 
    </init-param> 
    <load-on-startup>2</load-on-startup>` 

Answer 1

前提是你得從https://github.com/wordnik/swagger-ui文件正確複製到您的項目（目錄dist必須複製到你的src/main/webapp），那麼你就可以訪問http://.../MyService/index.html API文檔。不要忘了修改index.html使揚鞭知道要加載的API文檔：

window.swaggerUi = new SwaggerUi({ 
    url: "http://localhost:8080/MyService/rest/api-docs", 

在web.xml的API基本路徑必須被設置爲http://.../MyService/rest如果rest是您在您的實現已定義的應用程序路徑類別javax.ws.rs.core.Application通過使用註釋@ApplicationPath。

這裏是什麼，我通常做一個例子（我不使用web.xml進行配置）：

@ApplicationPath("api") 
public class MyRestApplication extends Application 
{ 
    @Override 
    public Set<Class<?>> getClasses() 
    { 
     Set<Class<?>> resources = new HashSet<Class<?>>(); 
     resources.add(ApiListingResource.class); 
     resources.add(ApiDeclarationProvider.class); 
     resources.add(ApiListingResourceJSON.class); 
     resources.add(ResourceListingProvider.class); 
     resources.add(Ping.class); // my own resource class 
     swaggerConfiguration(); 
     return resources; 
    } 

    private void swaggerConfiguration() 
    { 
     SwaggerConfig swaggerConfig = new SwaggerConfig(); 
     ConfigFactory.setConfig(swaggerConfig); 
     swaggerConfig.setApiVersion("0.0.1"); 
     swaggerConfig.setBasePath("http://localhost:8080/MyService/api"); 
     ScannerFactory.setScanner(new DefaultJaxrsScanner()); 
     ClassReaders.setReader(new DefaultJaxrsApiReader()); 
    } 
} 

Answer 2

的swagger.api.basepath參數不在您揚鞭安裝保持index.html。 Swagger使用它提供了通過Swagger UI調用REST端點的功能，因此它被呈現到Swagger使用的鏈接中。

您下載Swagger UI並將其放入您的WebContent文件夾中。然後您可以加載Swagger UI http://localhost:8080/swagger/。

的web.xml應該看起來像：

<servlet> 
    <servlet-name>jersey-servlet</servlet-name> 
    <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class> 
    <init-param> 
     <param-name>javax.ws.rs.Application</param-name> 
     <param-value>### Your Application or ResourceConfig ###</param-value> 
    </init-param> 
    <init-param> 
     <param-name>jersey.config.server.provider.packages</param-name> 
     <param-value>io.swagger.jaxrs.listing, 
        ### com.your.rest.package ### 
     </param-value> 
    </init-param> 

    <load-on-startup>1</load-on-startup> 
</servlet> 

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

... 


<servlet> 
    <servlet-name>JerseyJaxrsConfig</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>/MyService/rest</param-value> 
    </init-param> 
    <init-param> 
     <param-name>scan.all.resources</param-name> 
     <param-value>true</param-value> 
    </init-param> 
    <load-on-startup>2</load-on-startup> 
</servlet> 

Answer 3

下面是使用Spring，Tomcat的，球衣，行家，招搖最簡單的例子。 以下是項目結構。

代碼的HelloWorldService。

package com.rest; 
import com.wordnik.swagger.annotations.Api; 
import com.wordnik.swagger.annotations.ApiOperation; 
import com.wordnik.swagger.annotations.ApiResponse; 
import com.wordnik.swagger.annotations.ApiResponses; 

import javax.ws.rs.GET; 
import javax.ws.rs.Path; 
import javax.ws.rs.PathParam; 
import javax.ws.rs.Produces; 
import javax.ws.rs.core.MediaType; 

/** 
* Created by neerbans on 11/3/2016. 
*/ 

@Path("/hello") 
@Api(value = "/hello", description = "print hello world") 
public class HelloWorldService { 

    @ApiOperation(
      value = "method api", 
      notes = "method api notes" 
    ) 
    @ApiResponses(value = { 
      @ApiResponse(code = 200, message = "success"), 
      @ApiResponse(code = 500, message = "error") 
    }) 
    @Produces({MediaType.TEXT_PLAIN}) 
    @GET 
    @Path("/{param}") 
    public String getMsg(
      @PathParam("param") 
      String msg 
    ) { 

     String output = "Jersey say : " + msg; 

     return output; 
    } 

} 

SwaggerApp.class

package com.rest; 

import com.wordnik.swagger.config.ConfigFactory; 
import com.wordnik.swagger.config.ScannerFactory; 
import com.wordnik.swagger.config.SwaggerConfig; 
import com.wordnik.swagger.jaxrs.config.ReflectiveJaxrsScanner; 
import com.wordnik.swagger.jaxrs.listing.ApiDeclarationProvider; 
import com.wordnik.swagger.jaxrs.listing.ApiListingResource; 
import com.wordnik.swagger.jaxrs.listing.ApiListingResourceJSON; 
import com.wordnik.swagger.jaxrs.listing.ResourceListingProvider; 
import com.wordnik.swagger.jaxrs.reader.DefaultJaxrsApiReader; 
import com.wordnik.swagger.reader.ClassReaders; 
import org.glassfish.jersey.message.MessageProperties; 
import org.glassfish.jersey.server.ResourceConfig; 
import org.glassfish.jersey.server.ServerProperties; 

import javax.annotation.PostConstruct; 

/** 
* Created by neerbans on 11/3/2016. 
*/ 
public class SwaggerApp extends ResourceConfig { 

    public SwaggerApp() { 
     register(HelloWorldService.class); 

     register(ApiListingResource.class); 
     register(ApiDeclarationProvider.class); 
     register(ApiListingResourceJSON.class); 
     register(ResourceListingProvider.class); 

     property(MessageProperties.XML_FORMAT_OUTPUT, true); 
     property(ServerProperties.TRACING, "ALL"); 
    } 

    @PostConstruct 
    public void initializeSwaggerConfiguration() { 

     final ReflectiveJaxrsScanner scanner = new ReflectiveJaxrsScanner(); 
     scanner.setResourcePackage("com.rest"); 
     ScannerFactory.setScanner(scanner); 
     ClassReaders.setReader(new DefaultJaxrsApiReader()); 
     final SwaggerConfig config = ConfigFactory.config(); 
     config.setApiVersion("1.0"); 
     config.setBasePath("http://localhost:8080/jax-rs/rest"); 
    } 
} 

的applicationContext.xml

<?xml version="1.0" encoding="UTF-8"?> 
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:context="http://www.springframework.org/schema/context" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd"> 
    <context:component-scan base-package="com.rest" /> 
    <context:annotation-config /> 
</beans> 

Web.xml中

<!DOCTYPE web-app PUBLIC 
"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" 
"http://java.sun.com/dtd/web-app_2_3.dtd" > 

<web-app> 
    <display-name>Archetype Created Web Application</display-name> 

    <!--<servlet>--> 
     <!--<servlet-name>jersey-servlet</servlet-name>--> 
     <!--<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>--> 
     <!--<init-param>--> 
      <!--<param-name>com.sun.jersey.config.property.packages</param-name>--> 
      <!--<param-value>com.rest</param-value>--> 
     <!--</init-param>--> 
     <!--<load-on-startup>1</load-on-startup>--> 
    <!--</servlet>--> 

    <context-param> 
     <param-name>contextConfigLocation</param-name> 
     <param-value>classpath:applicationContext.xml</param-value> 
    </context-param> 

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

    <listener> 
     <listener-class>org.springframework.web.context.request.RequestContextListener</listener-class> 
    </listener> 

    <servlet> 
     <servlet-name>Jersey Web Application</servlet-name> 
     <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class> 
     <init-param> 
      <param-name>javax.ws.rs.Application</param-name> 
      <param-value>com.rest.SwaggerApp</param-value> 
     </init-param> 
     <load-on-startup>1</load-on-startup> 
    </servlet> 

    <servlet-mapping> 
     <servlet-name>Jersey Web Application</servlet-name> 
     <url-pattern>/rest/*</url-pattern> 
    </servlet-mapping> 
</web-app> 

的pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> 
    <parent> 
     <artifactId>nb</artifactId> 
     <groupId>com.edifecs</groupId> 
     <version>1.0-SNAPSHOT</version> 
    </parent> 
    <modelVersion>4.0.0</modelVersion> 
    <artifactId>jax-rs</artifactId> 
    <packaging>war</packaging> 
    <name>jax-rs Maven Webapp</name> 
    <url>http://maven.apache.org</url> 
    <dependencies> 
     <dependency> 
      <groupId>junit</groupId> 
      <artifactId>junit</artifactId> 
      <version>3.8.1</version> 
      <scope>test</scope> 
     </dependency> 
     <dependency> 
      <groupId>org.glassfish.jersey.containers</groupId> 
      <artifactId>jersey-container-servlet</artifactId> 
      <version>2.22.2</version> 
     </dependency> 
     <dependency> 
      <groupId>com.wordnik</groupId> 
      <artifactId>swagger-jaxrs_2.10</artifactId> 
      <version>1.3.12</version> 
     </dependency> 
     <dependency> 
      <groupId>org.springframework</groupId> 
      <artifactId>spring-web</artifactId> 
      <version>4.1.4.RELEASE</version> 
     </dependency> 
    </dependencies> 
    <build> 
     <finalName>jax-rs</finalName> 
    </build> 
</project> 

設置完項目後。構建它並在Tomcat webapps文件夾中部署war文件。
運行Tomcat和命中以下網址：

http://localhost:8080/jax-rs/rest/api-docs

對於招搖的UI

http://localhost:8080/jax-rs

隨意問任何問題的情況下。

以下是鏈接至源代碼： https://github.com/neerbans/Euler/tree/master/Gauss/swagger