{"id":20013418,"url":"https://github.com/tminglei/binder-swagger-java","last_synced_at":"2025-05-04T21:32:08.723Z","repository":{"id":57723675,"uuid":"41963248","full_name":"tminglei/binder-swagger-java","owner":"tminglei","description":"A framework to bring form-binder-java to swagger","archived":false,"fork":false,"pushed_at":"2018-07-21T22:44:18.000Z","size":527,"stargazers_count":53,"open_issues_count":1,"forks_count":13,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-08T12:23:12.671Z","etag":null,"topics":["api-management","form-binder","swagger"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tminglei.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-09-05T14:09:27.000Z","updated_at":"2025-01-02T15:32:44.000Z","dependencies_parsed_at":"2022-09-26T21:50:34.221Z","dependency_job_id":null,"html_url":"https://github.com/tminglei/binder-swagger-java","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tminglei%2Fbinder-swagger-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tminglei%2Fbinder-swagger-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tminglei%2Fbinder-swagger-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tminglei%2Fbinder-swagger-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tminglei","download_url":"https://codeload.github.com/tminglei/binder-swagger-java/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252404355,"owners_count":21742539,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-management","form-binder","swagger"],"created_at":"2024-11-13T07:36:34.003Z","updated_at":"2025-05-04T21:32:08.065Z","avatar_url":"https://github.com/tminglei.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# binder-swagger-java\n\n[![Build Status](https://travis-ci.org/tminglei/binder-swagger-java.svg?branch=master)](https://travis-ci.org/tminglei/binder-swagger-java)\n\n`binder-swagger-java` is a simple api management solution, which let api maintainence and dev based on api easily.\n\n\n## Features\n- lightweight, less than 3000 line codes (framework + built-in route/fake data generating)\n- based on `form-binder-java`, allowing dynamic objects in operation's parameter/response definitions\n- directly integrate with `swagger-models`, allowing to operate swagger object when necessary\n- can generate mock response w/ fake data on demand for unimplemented api operations\n- high customizable, you can replace almost all of the core components\n\n\n## How it works\nYou 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.  \n_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)._\n\n![binder-swagger description](https://raw.githubusercontent.com/tminglei/binder-swagger-java/master/binder-swagger-java.png)\n\n\u003e _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._\n\n\n## How to use it\n#### 0) add the dependency to your project:\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.tminglei\u003c/groupId\u003e\n    \u003cartifactId\u003ebinder-swagger-java\u003c/artifactId\u003e\n    \u003cversion\u003e0.8.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n#### 1) define and register your api operations:\n```java\n// in `PetResource.java`\nstatic Mapping\u003c?\u003e petStatus = $(text(oneOf(Arrays.asList(\"available\", \"pending\", \"sold\"))))\n    .desc(\"pet status in the store\").example(\"available\").$$;\nstatic Mapping\u003c?\u003e pet = $(mapping(\n    field(\"id\", $(vLong()).desc(\"pet id\").example(gen(\"petId\").or(gen(() -\u003e faker.number().randomNumber()))).$$),\n    field(\"name\", $(text(required())).desc(\"pet name\").$$),\n    field(\"category\", attach(required()).to($(mapping(\n          field(\"id\", vLong(required())),\n          field(\"name\", text(required()))\n    )).refName(\"category\").desc(\"category belonged to\").$$)),\n    field(\"photoUrls\", $(list(text())).desc(\"pet's photo urls\").example(Arrays.asList(\"http://example.com/photo1\")).$$),\n    field(\"tags\", $(list(text())).desc(\"tags for the pet\").example(Arrays.asList(\"tag1\", \"tag2\")).$$),\n    field(\"status\", petStatus)\n)).refName(\"pet\").desc(\"pet info\").$$;\n\nstatic SharingHolder sharing = sharing().pathPrefix(\"/pet\").tag(\"pet\");\n\nstatic {\n    sharing.operation(GET, \"/{petId}\")\n        .summary(\"get pet by id\")\n        .parameter(param(longv()).in(\"path\").name(\"petId\").example(1l))\n        .response(200, response(pet))\n        .response(404, response().description(\"pet not found\"))\n        .notImplemented() // MARK IT `notImplemented`, THEN `binder-swagger-java` WILL GENERATE MOCK RESPONSE FOR YOU\n    ;\n}\n@GET\n@Path(\"/{petId}\")\npublic Response getPetById(@PathParam(\"petId\") String petId) throws NotFoundException, SQLException {\n...\n```\n#### 2) supplement your other swagger info:\n```java\n// in `Bootstrap.java`\nstatic {  // for swagger\n    swagger().info(info()\n        .title(\"Swagger Sample App\")\n        .description(\"This is a sample server Petstore server.  You can find out more about Swagger \" +\n              \"at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).  For this sample, \" +\n              \"you can use the api key `special-key` to test the authorization filters.\")\n        .termsOfService(\"http://swagger.io/terms/\")\n        .contact(contact().email(\"apiteam@swagger.io\"))\n        .license(license().name(\"Apache 2.0\")\n              .url(\"http://www.apache.org/licenses/LICENSE-2.0.html\")\n        )\n    ).host(\"localhost:8002\")\n    .basePath(\"/api\")\n    .consumes(\"application/json\")\n    .produces(\"application/json\")\n    .securityDefinition(\"api_key\", apiKeyAuth(\"api_key\", In.HEADER))\n    .securityDefinition(\"petstore_auth\", oAuth2()\n          .implicit(\"http://petstore.swagger.io/api/oauth/dialog\")\n          .scope(\"read:pets\", \"read your pets\")\n          .scope(\"write:pets\", \"modify pets in your account\")\n    ).tag(tag(\"pet\").description(\"Everything about your Pets\")\n          .externalDocs(externalDocs().description(\"Find out more\").url(\"http://swagger.io\"))\n    ).tag(tag(\"store\").description(\"Access to Petstore orders\")\n    ).tag(tag(\"user\").description(\"Operations about user\")\n          .externalDocs(externalDocs().description(\"Find out more about our store\").url(\"http://swagger.io\"))\n    );\n}\n```\n#### 3) configure the filter, which will serv the `swagger.json`:\n```xml\n// in `web.xml`\n\u003cfilter\u003e\n    \u003cfilter-name\u003eSwaggerFilter\u003c/filter-name\u003e\n    \u003cfilter-class\u003ecom.github.tminglei.swagger.SwaggerFilter\u003c/filter-class\u003e\n\n    \u003c!-- enable/disable swagger, default value: true\n    \u003cinit-param\u003e\n        \u003cparam-name\u003eenabled\u003c/param-name\u003e\n        \u003cparam-value\u003efalse\u003c/param-value\u003e\n    \u003c/init-param\u003e\n    --\u003e\n\n    \u003cinit-param\u003e\n        \u003cparam-name\u003escan-packages-and-classes\u003c/param-name\u003e\n        \u003cparam-value\u003ecom.example.resource; com.example.Bootstrap\u003c/param-value\u003e\n    \u003c/init-param\u003e\n\n    \u003c!-- specify the requestURI relative to base path, to fetch your swagger json, default '/swagger.json'\n    \u003cinit-param\u003e\n        \u003cparam-name\u003eswagger-uri\u003c/param-name\u003e\n        \u003cparam-value\u003e/swagger.json\u003c/param-value\u003e\n    \u003c/init-param\u003e\n    --\u003e\n\n    \u003c!-- configure your custom mapping converter\n    \u003cinit-param\u003e\n        \u003cparam-name\u003emapping-converter\u003c/param-name\u003e\n        \u003cparam-value\u003ecom.company.pkg.MyMappingConverter\u003c/param-value\u003e\n    \u003c/init-param\u003e\n    --\u003e\n\n    \u003c!-- enable/disable mock data generation, default value: true\n    \u003cinit-param\u003e\n        \u003cparam-name\u003efake-enabled\u003c/param-name\u003e\n        \u003cparam-value\u003efalse\u003c/param-value\u003e\n    \u003c/init-param\u003e\n    --\u003e\n\n    \u003c!-- configure your custom url router used by `binder-swagger-java`\n    \u003cinit-param\u003e\n        \u003cparam-name\u003eurl-router\u003c/param-name\u003e\n        \u003cparam-value\u003ecom.company.pkg.MyRouter\u003c/param-value\u003e\n    \u003c/init-param\u003e\n    --\u003e\n\n    \u003c!-- configure your custom data writer used by `binder-swagger-java`\n    \u003cinit-param\u003e\n        \u003cparam-name\u003edata-writer\u003c/param-name\u003e\n        \u003cparam-value\u003ecom.company.pkg.MyDataWriter\u003c/param-value\u003e\n    \u003c/init-param\u003e\n    --\u003e\n\u003c/filter\u003e\n\u003cfilter-mapping\u003e\n    \u003cfilter-name\u003eSwaggerFilter\u003c/filter-name\u003e\n    \u003curl-pattern\u003e/api/*\u003c/url-pattern\u003e\n\u003c/filter-mapping\u003e\n...\n```\n\n\n##### That's all. Enjoy it!\n\n\n\u003e For more usage details, pls check the example project [here](https://github.com/tminglei/binder-swagger-java/tree/master/example/java-jaxrs).\n\n\n## Q \u0026 A\n**Q:** Why use static code blocks to associate/register operation meta info instead of annotations?  \n**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.  \n_(p.s. because of this, we can't also use existing frameworks, like `springfox`.)_\n\n\n## License\nThe BSD License, Minglei Tu \u0026lt;tmlneu@gmail.com\u0026gt;\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftminglei%2Fbinder-swagger-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftminglei%2Fbinder-swagger-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftminglei%2Fbinder-swagger-java/lists"}