从现有的REST API生成Swagger文档

Question

给定现有的接受并返回json且具有jackson注释类型的JAX-RS注释API，有没有一种方法可以生成一些YAML Swagger文档？ 我的计划B是编写一些代码，这些代码使用反射来查找REST注释的类型，为其参数和返回值创建哈希图，然后对那些类进行Jackson注释的爬网，并以此方式生成文档。

我宁愿使用已经存在的解决方案来编写一次性的东西。 我发现这个Swagger模块声称可以解析Jackson的配置（ https://github.com/FasterXML/jackson-module-swagger ），但是我对Swagger的了解还不足以了解什么是模块以及是否可以使用它从现有代码生成Swagger。

Answer 1

您可能想看看这个项目： https : //github.com/sdaschner/jaxrs-analyzer

它可以为JAX-RS自动生成Swagger文档。 据我了解，Jackson的特定注释未考虑在内。

Answer 2

Swagger将为带注释的方法生成交互式文档。 您无需编写自己的搜寻器。 添加库：

    <dependency>
        <groupId>com.wordnik</groupId>
        <artifactId>swagger-jaxrs_2.10</artifactId>
        <version>1.3.13</version>
        <scope>compile</scope>
    </dependency>

配置它：

private void configureSwagger(String swaggerBasePath){
    SwaggerConfig swaggerConfig = new SwaggerConfig();
    ConfigFactory.setConfig(swaggerConfig);
    swaggerConfig.setSwaggerVersion("Version");
    swaggerConfig.setApiVersion("1"); 
    swaggerConfig.setBasePath("http://example.com:8080/your-service");
    ScannerFactory.setScanner(new DefaultJaxrsScanner());
    ClassReaders.setReader(new DefaultJaxrsApiReader());
}

注释您的服务和方法：

@Path("/v1/items")
@Api(value = "/v1/items", description = "API description for Swagger")
public class ItemsService {

      @GET
      @Path("/list")
      @ApiOperation(value = "Get items list", notes = "Returns items list.")
      @Consumes(MediaType.APPLICATION_JSON)
      @Produces(MediaType.APPLICATION_JSON)
      public ItemsResponse getItems(){
          ...
      }

}

添加Swagger UI文件夹并修改其index.html源，以加载REST服务文档URL。