带有 JAX-RS Jersey 2 和 Grizzly 的 Swagger 文档答案

【问题标题】：Swagger documentation with JAX-RS Jersey 2 and Grizzly带有 JAX-RS Jersey 2 和 Grizzly 的 Swagger 文档
【发布时间】：2016-02-14 08:43:20
【问题描述】：

我已经使用 JAX-RS 实现了一个 Rest web 服务（功能不相关）。现在我想使用 Swagger 生成它的文档。我已按照以下步骤操作：

1) 在build.gradle 中，我得到了我需要的所有依赖项：

compile 'org.glassfish.jersey.media:jersey-media-moxy:2.13'

2) 我用 Swagger 注释记录我的代码

3) 我在我的 Application 子类中连接了 Swagger：

public class ApplicationConfig extends ResourceConfig  {

    /**
     * Main constructor
     * @param addressBook a provided address book
     */
    public ApplicationConfig(final AddressBook addressBook) {
        register(AddressBookService.class);
        register(MOXyJsonProvider.class);
        register(new AbstractBinder() {
            @Override
            protected void configure() {
                bind(addressBook).to(AddressBook.class);
            }
        });
        register(io.swagger.jaxrs.listing.ApiListingResource.class);
        register(io.swagger.jaxrs.listing.SwaggerSerializers.class);

        BeanConfig beanConfig = new BeanConfig();
        beanConfig.setVersion("1.0.2");
        beanConfig.setSchemes(new String[]{"http"});
        beanConfig.setHost("localhost:8282");
        beanConfig.setBasePath("/");
        beanConfig.setResourcePackage("rest.addressbook");
        beanConfig.setScan(true);
    }
}

但是，当我在http://localhost:8282/swagger.json 中为我服务时，我得到了这个输出。

你可以查看我的公开回购here。

【问题讨论】：

您正在尝试在没有应用程序上下文的情况下访问您的swagger.json。尝试向 URL 添加上下文：http://localhost:8282/app/swagger.json
我用那个 URL 得到 404（使用相同的代码）。
也许你可以从这个answer得到一些启发。

标签： rest jax-rs swagger jersey-2.0 grizzly

【解决方案1】：

在这种情况下（当对问题没有真正的解释时）我会抛出ExceptionMapper<Throwable>。通常对于与服务器相关的异常，没有映射器来处理异常，因此它会冒泡到容器中，我们会收到一个无用的 500 状态代码，可能还有一些来自服务器的无用消息（正如您从 Grizzly 看到的那样）。

import javax.ws.rs.WebApplicationException;
import javax.ws.rs.core.Response;
import javax.ws.rs.ext.ExceptionMapper;

public class DebugMapper implements ExceptionMapper<Throwable>  {

    @Override
    public Response toResponse(Throwable exception) {
        exception.printStackTrace();
        if (exception instanceof WebApplicationException) {
            return ((WebApplicationException)exception).getResponse();
        }
        return Response.serverError().entity(exception.getMessage()).build();
    }  
}

然后只需注册应用程序

public ApplicationConfig(final AddressBook addressBook) {
    ...
    register(DebugMapper.class);
}

当您再次运行应用程序并尝试访问端点时，您现在将看到一个堆栈跟踪，其中包含异常原因

java.lang.NullPointerException
  at io.swagger.jaxrs.listing.ApiListingResource.getListingJson(ApiListingResource.java:90)

如果您查看source code 的ApiListingResource.java:90，您会看到

Swagger swagger = (Swagger) context.getAttribute("swagger");

这里唯一可能导致 NPE 的是context，scrolling up 会告诉你它是ServletContext。现在这是它为空的原因。为了让那里甚至成为 ServletContext，应用程序需要在 Servlet 环境中运行。但是看看你的设置：

HttpServer server = GrizzlyHttpServerFactory
        .createHttpServer(uri, new ApplicationConfig(ab));

这不会创建 Servlet 容器。它只创建一个 HTTP 服务器。您拥有创建 Servlet 容器 (jersey-container-grizzly2-servlet) 所需的依赖项，但您只需要使用它即可。因此，您应该这样做，而不是以前的配置，

ServletContainer sc = new ServletContainer(new ApplicationConfig(ab));
HttpServer server = GrizzlyWebContainerFactory.create(uri, sc, null, null); 
// you will need to catch IOException or add a throws clause

^{有关其他配置选项，请参阅GrizzlyWebContainerFactory 的 API。}

现在，如果您运行它并再次点击端点，您将看到 Swagger JSON。请注意，来自端点的响应只是 JSON，而不是文档接口。为此，您需要使用可以解释 JSON 的 Swagger UI。

感谢MCVE 项目顺便说一句。

【讨论】：

【解决方案2】：

Swagger 在 1.5.7 中修复了这个问题。它是Issue 1103，但修复是在去年 2 月推出的。 peeskillet 的答案仍然有效，但现在 OP 也是如此。

【讨论】：