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

Question

提问by user1529412

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.

我似乎无法理解如何集成 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

采纳答案by braunpet

Provided that you have correctly copied the files from https://github.com/wordnik/swagger-uito your project (directory distmust 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.htmlso that Swagger knows where to load the API docs:

如果您已将文件从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",

The API base path in your web.xmlmust be set to http://.../MyService/restif restis the application path that you have defined in your implementation of class javax.ws.rs.core.Applicationby using the annotation @ApplicationPath.

您的 API 基本路径web.xml必须设置为http://.../MyService/restifrest是您在类javax.ws.rs.core.Application的实现中使用注解定义的应用程序路径@ApplicationPath。

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

这是我通常做的一个例子（我不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

回答by Johannes Jander

The swagger.api.basepathparameter is notwhere 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.

该swagger.api.basepath参数不是您的 Swagger 安装保存index.html. 这是 Swagger 用来为您提供通过 Swagger UI 调用 REST 端点的功能的参数，因此它被呈现到 Swagger 使用的链接中。

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

您下载 Swagger UI 并将其放入您的WebContent文件夹中。然后，您可以在加载 Swagger UI http://localhost:8080/swagger/。

The web.xmlshould look like that:

本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

回答by Neeraj Bansal

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

这是使用 spring、tomcat、jersey、maven、swagger 的最简单示例。下面是项目结构。

Code for HelloWorldService.

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

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

网页.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 :

设置好项目后。构建它并在Tomcat webapps 文件夹中部署war 文件。
运行 Tomcat 并点击以下 URL：

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

For swagger-ui

对于 swagger-ui

http://localhost:8080/jax-rs

Feel free to ask in case of any queries.

如有任何疑问，请随时询问。

Below is the link to the source code : https://github.com/neeraj179/euler/tree/master/swagger

以下是源代码的链接：https: //github.com/neeraj179/euler/tree/master/swagger

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

提问by user1529412

采纳答案by braunpet

回答by Johannes Jander

回答by Neeraj Bansal

相关推荐

最近更新

标签

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

提问by user1529412

采纳答案by braunpet

回答by Johannes Jander

回答by Neeraj Bansal

相关推荐

Java 连接到 postgresql：致命：数据库“xxx”不存在

Java 发送数据时，从 Android 应用中的 Firebase 检索 ServerValue.Timestamp

空列表上的Java 8流操作

Java 8：多个单位中两个 LocalDateTime 之间的差异

相关推荐

最近更新

标签