binder-swagger-javaSwagger API 框架-技术圈

`binder-swagger-java` 是一套简易的 API 管理方案。它可以生成 swagger ui 可以浏览、交互的 API，还可以自动为没有实现的接口/操作生成数据和响应。

它如何工作的？

我们在类的静态块中定义 API 元数据信息，在类扫描/加载时，这些数据被收集到一个全局的 swagger 对象中，这样，当收到获取 swagger.json 的请求时，程序就可以用这个 swagger 对象直接响应了。

binder-swagger description

示例项目

下载了项目源码以后，进入 example/java-jaxrs 目录

> mvn clean
> mvn jetty:run-war

然后浏览器打开：http://localhost:8002
就可以看到效果了 ^^

如何使用？

// in `PetResource.java`
static Mapping petStatus = $(text(oneOf(Arrays.asList("available", "pending", "sold"))))
    .desc("pet status in the store").example("available").$$;
static Mapping pet = $(mapping(
    field("id", $(vLong()).desc("pet id").example(gen("petId").or(gen(() -> faker.number().randomNumber()))).$$),
    field("name", $(text(required())).desc("pet name").$$),
    field("category", attach(required()).to($(mapping(
          field("id", vLong(required())),
          field("name", text(required()))
    )).refName("category").desc("category belonged to").$$)),
    field("photoUrls", $(list(text())).desc("pet's photo urls").example(Arrays.asList("http://example.com/photo1")).$$),
    field("tags", $(list(text())).desc("tags for the pet").example(Arrays.asList("tag1", "tag2")).$$),
    field("status", petStatus)
)).refName("pet").desc("pet info").$$;

static SharingHolder sharing = sharing().pathPrefix("/pet").tag("pet");

static {
    sharing.operation(GET, "/{petId}")
        .summary("get pet by id")
        .parameter(param(longv()).in("path").name("petId").example(1l))
        .response(200, response(pet))
        .response(404, response().description("pet not found"))
        .notImplemented() // MARK IT `notImplemented`, THEN `binder-swagger-java` WILL GENERATE MOCK RESPONSE FOR YOU
    ;
}
@GET
@Path("/{petId}")
public Response getPetById(@PathParam("petId") String petId) throws NotFoundException, SQLException {
...

0. 把 binder-swagger-java 依赖加入项目

1. (如上)定义/注册你的 API 操作

2. 补充其他 swagger info

3. 在 web.xml 里配置 SwaggerFilter

就这样，可以用了。

Q & A

Q: 为什么使用静态代码块而不是注释来注册/关联操作的元数据信息？

A：因为注释不能满足需求，注释要求静态定义的数据类型，而我们的项目很多按需生成的数据没有定义 Java Bean。

--------------------------------------------------

更多细节请访问项目网站。