在 JBoss / Wildfly 9 上使用 JAX-RS 项目设置 Swagger.io 问题

Question

我实现了一个项目，它使用一个非常简单的 JAX-RS 后端向基于 AngularJS 的 UI 提供数据。这些是独立的模块并部署在 Wildfly 9 上。为了有一个很好的 REST 端点文档，我遇到了 swagger.io，它看起来很合适。但是，由于我的项目结构略有不同，因此我无法按照文档和示例设置 swagger。

当前状态

我可以访问返回的http://localhost:8080/service/swagger.json

{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": ""
    },
    "host": "localhost:8080",
    "basePath": "/service",
    "schemes": ["http"]
}

但是 swagger-ui（swagger.json 已正确链接）没有显示我的任何 REST 端点。

我认为这个问题可能与为 Wildfly 设置的 basePath 或 contextRoot 有关，但这只是一个模糊的猜测。除此之外，我什至不确定要使用什么大张旗鼓的 JAX-RS 实现。我想既然我使用 Wildfly (JBoss)，它应该是 Resteasy，但大摇大摆的 Jersey 设置文档似乎更合适。

我的 REST 端点看起来像像这样http://localhost:8080/service/users/register

相关资源

pom.xml

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-core</artifactId>
    <version>1.5.4</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-jaxrs</artifactId>
    <version>1.5.4</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.5.4</version>
</dependency>

web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
         version="3.1">
    <display-name>service</display-name>

    <servlet>
        <servlet-name>javax.ws.rs.core.Application</servlet-name>
        <init-param>
            <param-name>jersey.config.server.provider.packages</param-name>
            <param-value>
                io.swagger.jaxrs.listing,
                jfs.service.services
            </param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>javax.ws.rs.core.Application</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>

    <servlet>
        <servlet-name>Jersey2Config</servlet-name>
        <servlet-class>io.swagger.jaxrs.config.DefaultJaxrsConfig</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>http://localhost:8080/service</param-value>
        </init-param>
        <load-on-startup>2</load-on-startup>
    </servlet>
</web-app>

jboss-web.xml

<?xml version="1.0" encoding="UTF-8"?>
<jboss-web>
    <context-root>/service/</context-root>
</jboss-web>

UserWebService 为例

package jfs.service.services;

import com.google.gson.Gson;
import io.swagger.annotations.*;
import jfs.data.dataobjects.UserDO;
import jfs.data.dataobjects.enums.UserType;
import jfs.service.sessions.Session;
import jfs.transferdata.transferobjects.*;

import javax.inject.Inject;
import javax.ws.rs.Consumes;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import java.util.List;

@Path("/users")
@Api(tags = {"users"}, value = "/users", description = "Operations about user")
public class UserWebService {
    @Inject
    UserService service;

    @POST
    @ApiOperation(value = "Register company",
        notes = "A user account for company will be created.",
        position = 1)
    @Path("/register")
    @Consumes("application/json")
    @Produces("application/json")
    public Boolean registerCompany(RegisterDTO register){
        Boolean result = false;
        result = this.service.registerUser(register.email, register.password, UserType.COMPANY);
        return result;
    }
}

Answer 1

经过一些尝试和错误后，我想出了一个让它工作的方法。为了连接 swagger-core，我从手动注册资源类切换到自动扫描和注册。这需要将配置和初始化从 web.xml 更改为 BeanConfig，例如一个小服务程序。

我不知道不同方法的（缺点）优点（如果有的话）——也许有人可以分享一些见解。

除此之外，这对我来说是一个可行的解决方案：

web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
         version="3.1">
    <display-name>service</display-name>

    <servlet>
        <servlet-name>javax.ws.rs.core.Application</servlet-name>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>javax.ws.rs.core.Application</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>

    <context-param>
        <param-name>resteasy.scan</param-name>
        <param-value>true</param-value>
    </context-param>

    <servlet>
        <servlet-name>SwaggerServlet</servlet-name>
        <servlet-class>jfs.service.services.SwaggerServlet</servlet-class>
        <load-on-startup>2</load-on-startup>
    </servlet>
</web-app>

SwaggerServlet.java

package jfs.service.services;

import io.swagger.jaxrs.config.BeanConfig;
import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;

public class SwaggerServlet extends HttpServlet {
    @Override
    public void init(ServletConfig config) throws ServletException {
        super.init(config);

        BeanConfig beanConfig = new BeanConfig();
        beanConfig.setVersion("1.0.0");
        beanConfig.setSchemes(new String[]{"http"});
        beanConfig.setHost("localhost:8080");
        beanConfig.setBasePath("/service");
        beanConfig.setResourcePackage("jfs.service.services");
        beanConfig.setScan(true);
    }
}