binder-swagger-javaSwagger API 框架

`binder-swagger-java` 是一套簡易的 API 管理方案。它可以生成 swagger ui 可以瀏覽、交互的 API，還可以自動為沒有實現(xiàn)的接口/操作生成數(shù)據(jù)和響應(yīng)。

它如何工作的？

我們在類的靜態(tài)塊中定義 API 元數(shù)據(jù)信息，在類掃描/加載時，這些數(shù)據(jù)被收集到一個全局的 swagger 對象中，這樣，當(dāng)收到獲取 swagger.json 的請求時，程序就可以用這個 swagger 對象直接響應(yīng)了。

示例項目

下載了項目源碼以后，進(jìn)入 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. 補(bǔ)充其他 swagger info

3. 在 web.xml 里配置 SwaggerFilter

就這樣，可以用了。

Q & A

Q: 為什么使用靜態(tài)代碼塊而不是注釋來注冊/關(guān)聯(lián)操作的元數(shù)據(jù)信息？

A：因為注釋不能滿足需求，注釋要求靜態(tài)定義的數(shù)據(jù)類型，而我們的項目很多按需生成的數(shù)據(jù)沒有定義 Java Bean。

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

更多細(xì)節(jié)請訪問項目網(wǎng)站。