https://github.com/tminglei/binder-swagger-java
A framework to bring form-binder-java to swagger
https://github.com/tminglei/binder-swagger-java
api-management form-binder swagger
Last synced: about 1 year ago
JSON representation
A framework to bring form-binder-java to swagger
- Host: GitHub
- URL: https://github.com/tminglei/binder-swagger-java
- Owner: tminglei
- License: bsd-2-clause
- Created: 2015-09-05T14:09:27.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2018-07-21T22:44:18.000Z (almost 8 years ago)
- Last Synced: 2025-04-08T12:23:12.671Z (about 1 year ago)
- Topics: api-management, form-binder, swagger
- Language: Java
- Homepage:
- Size: 515 KB
- Stars: 53
- Watchers: 10
- Forks: 13
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# binder-swagger-java
[](https://travis-ci.org/tminglei/binder-swagger-java)
`binder-swagger-java` is a simple api management solution, which let api maintainence and dev based on api easily.
## Features
- lightweight, less than 3000 line codes (framework + built-in route/fake data generating)
- based on `form-binder-java`, allowing dynamic objects in operation's parameter/response definitions
- directly integrate with `swagger-models`, allowing to operate swagger object when necessary
- can generate mock response w/ fake data on demand for unimplemented api operations
- high customizable, you can replace almost all of the core components
## How it works
You define the api meta data in classes' static code blocks, then it was collected to a static global swagger object when class scan/loading, so when requested, the program can serve it right now.
_With swagger.json, the swagger-ui can render the API menu in the browser. Then you can browse, fill parameters and send to/receive from service impls (p.s. the service urls were included in swagger.json)._
> _p.s. based on [`form-binder-java`](https://github.com/tminglei/form-binder-java) and [`swagger-models`](https://github.com/swagger-api/swagger-core), `binder-swagger-java` enable you to define dynamic data structures and operate the swagger object directly when necessary, so it's more expressive in theory._
## How to use it
#### 0) add the dependency to your project:
```xml
com.github.tminglei
binder-swagger-java
0.8.0
```
#### 1) define and register your api operations:
```java
// 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 {
...
```
#### 2) supplement your other swagger info:
```java
// in `Bootstrap.java`
static { // for swagger
swagger().info(info()
.title("Swagger Sample App")
.description("This is a sample server Petstore server. You can find out more about Swagger " +
"at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, " +
"you can use the api key `special-key` to test the authorization filters.")
.termsOfService("http://swagger.io/terms/")
.contact(contact().email("apiteam@swagger.io"))
.license(license().name("Apache 2.0")
.url("http://www.apache.org/licenses/LICENSE-2.0.html")
)
).host("localhost:8002")
.basePath("/api")
.consumes("application/json")
.produces("application/json")
.securityDefinition("api_key", apiKeyAuth("api_key", In.HEADER))
.securityDefinition("petstore_auth", oAuth2()
.implicit("http://petstore.swagger.io/api/oauth/dialog")
.scope("read:pets", "read your pets")
.scope("write:pets", "modify pets in your account")
).tag(tag("pet").description("Everything about your Pets")
.externalDocs(externalDocs().description("Find out more").url("http://swagger.io"))
).tag(tag("store").description("Access to Petstore orders")
).tag(tag("user").description("Operations about user")
.externalDocs(externalDocs().description("Find out more about our store").url("http://swagger.io"))
);
}
```
#### 3) configure the filter, which will serv the `swagger.json`:
```xml
// in `web.xml`
SwaggerFilter
com.github.tminglei.swagger.SwaggerFilter
scan-packages-and-classes
com.example.resource; com.example.Bootstrap
SwaggerFilter
/api/*
...
```
##### That's all. Enjoy it!
> For more usage details, pls check the example project [here](https://github.com/tminglei/binder-swagger-java/tree/master/example/java-jaxrs).
## Q & A
**Q:** Why use static code blocks to associate/register operation meta info instead of annotations?
**A:** Well, because we can't use annotations here. Annotation requires static defined data types, but we didn't define java beans in our project.
_(p.s. because of this, we can't also use existing frameworks, like `springfox`.)_
## License
The BSD License, Minglei Tu <tmlneu@gmail.com>