Swagger 不生成 REST 文档答案

【问题标题】：Swagger not generating the REST documentationSwagger 不生成 REST 文档
【发布时间】：2015-12-01 08:33:00
【问题描述】：

我正在尝试让 Swagger 自动生成我的 REST API 的 che 文档，但我只得到部分结果。

我正在使用 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;
    }

}

然后我运行 Web 应用程序（在 Wildfly 9 服务器上）并转到 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 init 方法 BeanConfig.classes() 中正确发现了我的 REST 类。

【问题讨论】：

您希望在您的 swagger 文档中看到什么？据我所知，您的课程 WebappInit 没有任何标有 JAXRS 注释的方法。
我希望看到我的 REST 服务列表以及使用它们的有用数据（HTTP 方法、端点、请求和响应主体）。 “据我所知，您的类 WebappInit 没有任何标有 JAXRS 注释的方法”是什么意思？在我的 WebappInit.getClasses() 方法中，我添加了 REST 服务类。这还不够吗？
我个人从未见过这种技术。我相信这对你有用，但我不明白如何。例如，您如何调用ApiListingResource 服务？使用像/rest/listing这样的网址？
不确定是否与此问题直接相关，但您会遇到另一个问题，与this 有关。如果您正在对资源进行类路径扫描，则只需注册 swagger 类即可禁用类路径扫描。
@AlexR：我遵循了 JAX-RS 应用程序的 Swagger 指南，它扩展了 Application 类：github.com/swagger-api/swagger-core/wiki/…

标签： java rest maven jax-rs swagger

【解决方案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 ();
    }
}

【讨论】：

【解决方案2】：

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

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

【讨论】：

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

【解决方案3】：

你必须在你的资源类中添加@Api注解并在setResourcePackage方法中加载资源包。它应该发挥作用。

【讨论】：