java - Swagger 不生成 REST 文档

Question

我试图让 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 初始化方法 BeanConfig.classes() 中我的 REST 类是否被正确发现。

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