从现有 REST 生成 Swagger 文档 api

Question

鉴于现有的 JAX-RS 注释 API 接受 & returns json，带有 jackson 注释类型，有没有一种方法可以生成一些 YAML Swagger 文档？我的 B 计划是编写一些代码，使用反射来查找 REST 注释类型，制作它们的参数和 returns 的哈希图，然后爬取那些类以获取 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。

从现有 REST 生成 Swagger 文档 api

Generating Swagger documentation from existing REST api

java

jax-rs

swagger

jersey-2.0

swagger-ui