如何将 Swagger 与 Maven + Java + Jersey + Tomcat 集成

Question

I can't seem to understand how to integrate Swagger to generate API documentation. url: ####:8080/MyService/rest/users/getall
I have added Annotations to code and dependency.
I try to visit: ####:8080/MyService/rest/ but says its not found.

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

Provided that you have correctly copied the files from https://github.com/wordnik/swagger-ui to your project (directory dist must be copied to your src/main/webapp ), then you can access the API documentation on http://.../MyService/index.html . Don't forget to modify index.html so that Swagger knows where to load the API docs:

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

The API base path in your web.xml must be set to http://.../MyService/rest if rest is the application path that you have defined in your implementation of class javax.ws.rs.core.Application by using the annotation @ApplicationPath .

Here is an example of what I usually do (I don't use web.xml for configuration):

@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

Here is the simplest example using spring, tomcat, jersey, maven, swagger. Below is the project structure.

Code for 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>

After setting the project. Build it and deploy the war file in Tomcat webapps folder.
Run Tomcat and hit below URLs :

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

For swagger-ui

http://localhost:8080/jax-rs

Answer 3

The swagger.api.basepath parameter is not where your Swagger installation keeps the index.html . It is a parameter Swagger uses to offer you the capability to call your REST endpoints via the Swagger UI, so it get's rendered into the links Swagger uses.

You download the Swagger UI and put it into your WebContent folder. You can then load the Swagger UI at http://localhost:8080/swagger/ .

The web.xml should look like that:

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

I've had a good experience setting up Swagger using BeanConfig and a plain HttpServlet

public class SwaggerBootstrap extends HttpServlet {

    @Override
    public void init(ServletConfig config) throws ServletException {
        super.init(config);

        BeanConfig beanConfig = new BeanConfig();
        beanConfig.setVersion("1.0.0");
        beanConfig.setTitle("MyAppWeb App UI");
        // description can accept markdown
        beanConfig.setDescription("This is an overview of all the REST endpoints. Find out more about Swagger at [http://swagger.io](http://swagger.io)");
        beanConfig.setSchemes(new String[]{"https"});
        beanConfig.setHost("localhost:8443");
        beanConfig.setBasePath("/app");
        beanConfig.setResourcePackage("com.myapp.web.app");
        // enables scan
        beanConfig.setScan(true);
    }
}

(The com.myapp.web.app resource package is where I put all my Jersey resources)

Then, I've just registered the servlet in web.xml

<servlet>
    <servlet-name>SwaggerBootstrap</servlet-name>
    <servlet-class>com.myapp.web.app.SwaggerBootstrap</servlet-class>
    <load-on-startup>2</load-on-startup>
</servlet>

And of course I've to register listing for all of this to work

<servlet>
    <servlet-name>Jersey REST Service</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;
          ...
    </param-value>
</init-param>

Reference in github