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但是swagger 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

经过一番尝试＆amp;错误我找到了一条能让它发挥作用的出路。为了连接swagger-core，我从资源类的手动注册切换到自动扫描和注册。这需要将配置和初始化从web.xml更改为BeanConfig，例如：一个servlet。

如果有的话，我不了解不同方法的（dis）优势 - 也许有人可以分享一些见解。

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

的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);
    }
}

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

1 个答案: