Swagger无法生成REST文档

Question

我正在尝试让Swagger自动生成我的REST API文档，但我只得到了部分结果。 我正在使用Resteasy。我添加了Maven Swagger依赖项。

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-jaxrs</artifactId>
    <version>1.5.3</version>
</dependency>

然后我配置了我的应用程序对象

package com.myapp.init;


import java.util.HashSet;
import java.util.Set;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

import io.swagger.jaxrs.config.BeanConfig;
import io.swagger.jaxrs.listing.ApiListingResource;
import io.swagger.jaxrs.listing.SwaggerSerializers;


@ApplicationPath("/rest")
public class WebappInit extends Application {

    public WebappInit() {
        BeanConfig beanConfig = new BeanConfig();
        beanConfig.setVersion("1.0.0");
        beanConfig.setSchemes(new String[]{"http"});
        beanConfig.setHost("theIP:8080");
        beanConfig.setBasePath("/myapp/rest/");
        beanConfig.setResourcePackage("the.resource.package");
        beanConfig.setScan(true);
        beanConfig.setPrettyPrint(true);

    }


    public Set<Class<?>> getClasses() {
        Set<Class<?>> s = new HashSet<Class<?>>();


        // here I add my REST WSs
        s.add(ApiListingResource.class);
        s.add(SwaggerSerializers.class);


        return s;
    }

}

然后我在Wildfly 9服务器上运行Web应用程序，并转到URL http://localhost:8080/myapp/rest/swagger.json。这是我得到的结果。

{
  swagger: "2.0",
  info: {
    version: "1.0.0"
  },
  host: "10.17.36.215:8080",
  basePath: "/devops/rest/",
  schemes: [
    "http"
  ]
}

似乎Swagger无法构建REST文档，即使我的REST端点是可访问的并添加到Swagger资源列表中。

可能出了什么问题？

谢谢

朱利奥

更新：我检查了Swagger初始化方法BeanConfig.classes（），我的REST类被正确发现。

- gvdm

---

你期望在你的Swagger文档中看到什么？就我所见，你的WebappInit类没有任何标记为JAXRS注解的方法。 - AlexR

我期望能够看到我的REST服务列表，包括有用的数据（HTTP方法、端点、请求和响应体），以便使用它们。你说的“就我所知，你的WebappInit类没有任何标记为JAXRS注释的方法”是什么意思？在我的WebappInit.getClasses()方法中，我添加了REST服务类。这不足够吗？ - gvdm

我个人从未见过这样的技术。我相信这对你有用，但我不明白它是如何工作的。例如，你如何调用ApiListingResource服务？使用像/rest/listing这样的URL吗？ - AlexR

@AlexR：我按照Swagger指南为扩展Application类的JAX-RS应用程序进行了设置：https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-JAX-RS-Project-Setup-1.5.X - gvdm

@peeskillet：好的，谢谢。但是我应该如何注册Swagger类？ - gvdm

Answer 1

您需要将@Api注解添加到您的资源类中。

例如：

package my.sample;
import io.swagger.annotations.Api;
import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.core.Response;

@Api
@Path ("/mypath")
public class MyResource
{
    @GET
    public Response myEndpoint()
    {
        return Response.ok ();
    }
}

- El Goodo

Answer 2

我想我明白了你的问题。你的根服务扩展了Application，允许动态构建资源层次结构。我认为swagger甚至不能支持这种技术，因为它在编译时生成其元数据（json文件）。

我总是使用基于注释的REST服务，即每个资源都用适当的@Path注释进行注释。框架会自动初始化所有资源，因此我不必从Application扩展我的根资源并实现getClasses()。在这种情况下，swagger可以通过分析JAXRS注释（如@Path、@PathParam、@GET、@POST等）提取所有资源并在编译时生成json文件。

- AlexR

---

我正在使用@Path和其他JAX-RS注释来注释我的REST类，但如果我不将这些类添加到WebappInit.getClasses()方法中，它们就无法被发现。 - gvdm

Answer 3

你需要在你的资源类上添加 @Api 注解，并在 setResourcePackage 方法中加载资源包。这样就可以实现魔法了。

- Vinay