带有JAX-RS Jersey 2和Grizzly的Swagger文档 [英] Swagger documentation with JAX-RS Jersey 2 and Grizzly

问题描述

我已经使用JAX-RS实现了Rest Web服务(该功能无关).现在，我想使用Swagger生成其文档.我已按照以下步骤操作:

I have implementated a Rest web service (the function is not relevant) using JAX-RS. Now I want to generate its documentation using Swagger. I have followed these steps:

1)在build.gradle中，我获得了所需的所有依赖项:

1) In build.gradle I get all the dependencies I need:

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

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

2) I documentate my code with Swagger annotations

3)我将Swagger连接到我的Application子类中:

3) I hook up Swagger in my Application subclass:

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中进入服务时，会得到此输出.

However, when going to my service in http://localhost:8282/swagger.json, I get this output.

您可以在此处查看我的公开仓库. /p>

You can check my public repo here.

推荐答案

我有时会把这样的情况(当没有真正的问题解释时)放入ExceptionMapper<Throwable>中.通常与服务器相关的异常，没有映射器可以处理该异常，因此它会冒泡到达容器，并且我们会从服务器中获得500个无用的状态码和一些无用的消息(如从Grizzly看到的那样).

It's times like this (when there is no real explanation for the problem) that I throw in an ExceptionMapper<Throwable>. Often with server related exceptions, there are no mappers to handle the exception, so it bubbles up to the container and we get a useless 500 status code and maybe some useless message from the server (as you are seeing from 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();
    }  
}

然后只需在应用程序中注册

Then just register with the application

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

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

When you run the application again and try to hit the endpoint, you will now see a stacktrace with the cause of the exception

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

如果您查看

If you look at the source code for ApiListingResource.java:90, you will see

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

这里唯一可能导致NPE的是context，它

The only thing here that could cause the NPE is the context, which scrolling up will show you it's the ServletContext. Now here's the reason it's null. In order for there to even be a ServletContext, the app needs to be run in a Servlet environment. But look at your set up:

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

这不会创建Servlet容器.它仅创建一个HTTP服务器.您具有创建Servlet容器(jersey-container-grizzly2-servlet)所需的依赖关系，但是您只需要使用它即可.因此，您应该代替以前的配置

This does not create a Servlet container. It only creates an HTTP server. You have the dependency required to create the Servlet container (jersey-container-grizzly2-servlet), but you just need to make use of it. So instead of the previous configuration, you should do

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

^请参阅现在，如果您运行它并再次命中端点，您将看到Swagger JSON.请注意，来自端点的响应只是JSON，而不是文档界面.为此，您需要使用可以解释JSON的Swagger UI.

Now if you run it and hit the endpoint again, you will see the Swagger JSON. Do note that the response from the endpoint is only the JSON, it is not the documentation interface. For that you need to use the Swagger UI that can interpret the JSON.

感谢 MCVE 项目BTW.

这篇关于带有JAX-RS Jersey 2和Grizzly的Swagger文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！