Как да интегрирате Swagger с Maven + Java + Jersey + Tomcat

При условие, че сте копирали правилно файловете от https://github.com/wordnik/swagger-ui във вашия проект ( директория dist трябва да бъде копирана във вашия src/main/webapp), тогава можете да получите достъп до документацията на API на http://.../MyService/index.html. Не забравяйте да промените index.html, така че Swagger да знае къде да зареди документите за API:

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

Основният път на API във вашия web.xml трябва да бъде настроен на 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( ) );
   }
}

Ето най-простият пример с използване на spring, tomcat, jersey, maven, swagger. По-долу е структурата на проекта.

Код за 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.
Стартирайте Tomcat и натиснете URL адресите по-долу:

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

За swagger-ui

http://localhost:8080/jax-rs

Параметърът swagger.api.basepath не е там, където вашата инсталация на Swagger запазва index.html. Това е параметър, който Swagger използва, за да ви предложи възможността да извиквате вашите REST крайни точки чрез потребителския интерфейс на Swagger, така че да бъде изобразен във връзките, използвани от Swagger.

Изтегляте потребителския интерфейс на Swagger и го поставяте във вашата папка WebContent. След това можете да заредите потребителския интерфейс на Swagger на 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>

Имам добър опит с настройването на Swagger с помощта на BeanConfig и обикновен 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);
    }
}

(Пакетът с ресурси com.myapp.web.app е мястото, където поставям всичките си ресурси от Джърси)

След това току-що регистрирах сървлета в 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>

И, разбира се, трябва да регистрирам списък, за да работи всичко това

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

Справка в github