java - 为什么 swagger ui 不显示我带注释的 REST 方法？

Question

我在配置 swagger 以查看我的 REST 方法时遇到问题。我在 Eclipse 和 Tomcat 7 中工作。我有以下简单的 REST 方法/类:

package com.rest;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;

@Api( value="/", description="Say hello class")
@Path("/")
public class Hello {

    @GET
    @Path("/hello")
    @ApiOperation(value="/hello", notes="hello method")
    public String sayHello() {
        return "Hello World!";
    }
}

我正在使用以下 web.xml

   <?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:javaee="http://java.sun.com/xml/ns/javaee"
    xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" version="3.0">
    <display-name>SwaggerTest</display-name>
    <welcome-file-list>
        <welcome-file>index.jsp</welcome-file>
    </welcome-file-list>
    <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>com.wordnik.swagger.jaxrs.json,com.rest</param-value>
        </init-param>
        <init-param>
            <param-name>jersey.config.server.provider.classnames</param-name>
            <param-value>
                com.wordnik.swagger.jersey.listing.ApiListingResourceJSON,
                com.wordnik.swagger.jersey.listing.JerseyApiDeclarationProvider,
                com.wordnik.swagger.jersey.listing.JerseyResourceListingProvider
            </param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>Jersey REST Service</servlet-name>
        <url-pattern>/api/*</url-pattern>
    </servlet-mapping>


    <servlet>
        <servlet-name>SwaggerJerseyJaxrsConfig</servlet-name>
        <servlet-class>com.wordnik.swagger.jersey.config.JerseyJaxrsConfig</servlet-class>
        <init-param>
            <param-name>api.version</param-name>
            <param-value>0.0.1</param-value>
        </init-param>
        <init-param>
            <param-name>swagger.api.basepath</param-name>
            <param-value>http://localhost:8080/api/</param-value>
        </init-param>
        <load-on-startup>2</load-on-startup>
    </servlet>

</web-app>

休息服务可在 http://localhost:8080/SwaggerTest/api/sayHello 上获得并在浏览器中显示正确的消息。该服务的 swagger 规范可在 http://localhost:8080/SwaggerTest/api-docs 获得。 .然而，返回的只是

{"apiVersion":"0.0.1","swaggerVersion":"1.2","apis":[{"path":"/","description":"Say hello class"}]}

GET sayHello() 方法发生了什么？或者这就是它应该返回的全部内容？

任何帮助将不胜感激。提前致谢。

大卫

附言Maven 依赖项是

<dependencies>
    <dependency>
        <groupId>org.glassfish.jersey.core</groupId>
        <artifactId>jersey-server</artifactId>
        <version>2.7</version>
    </dependency>

    <dependency>
        <groupId>org.glassfish.jersey.media</groupId>
        <artifactId>jersey-media-multipart</artifactId>
        <version>2.7</version>
    </dependency>

    <dependency>
        <groupId>org.glassfish.jersey.media</groupId>
        <artifactId>jersey-media-json-jackson</artifactId>
        <version>2.7</version>
    </dependency>

    <dependency>
        <groupId>com.wordnik</groupId>
        <artifactId>swagger-jersey2-jaxrs_2.10</artifactId>
        <version>1.3.12</version>
    </dependency>

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

    <dependency>
        <groupId>com.wordnik</groupId>
        <artifactId>swagger-servlet_2.10</artifactId>
        <version>1.3.12</version>
    </dependency>

    <dependency>
        <groupId>org.glassfish.jersey.containers</groupId>
        <artifactId>jersey-container-servlet-core</artifactId>
        <version>2.7</version>
    </dependency>


</dependencies>

Answer 1

问题是您使用的是生成 Swagger 1.2 定义的 swagger-core 1.3。 Swagger 1.2 不太喜欢基于根 (/) 的 API。如果将 @Api 的 value 更改为“/”以外的任何内容，您仍然可以显示它。这不会影响 API 本身，只会影响文档的托管方式。

如果你给它 value 例如“/root”，然后转到 http://localhost:8080/SwaggerTest/api-docs/root - 您会看到公开的服务。

此外，您通常使用旧版本的 swagger-core 和 Swagger。看起来你正在尝试与 Jersey 集成，所以你可以关注 https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5作为您的整合指南。这会生成 Swagger 2.0，它与根资源没有相同的问题。