{"id":18716344,"url":"https://github.com/killbill/killbill-swagger-coden","last_synced_at":"2026-02-23T23:37:24.418Z","repository":{"id":37866331,"uuid":"123993815","full_name":"killbill/killbill-swagger-coden","owner":"killbill","description":"Client code generation ","archived":false,"fork":false,"pushed_at":"2023-03-13T02:14:24.000Z","size":213,"stargazers_count":0,"open_issues_count":8,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-28T10:28:59.219Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Mustache","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/killbill.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-05T23:49:14.000Z","updated_at":"2021-10-01T22:08:56.000Z","dependencies_parsed_at":"2024-11-07T13:12:30.117Z","dependency_job_id":"7fcda918-4337-49b9-9bed-1eac087f0902","html_url":"https://github.com/killbill/killbill-swagger-coden","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/killbill%2Fkillbill-swagger-coden","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/killbill%2Fkillbill-swagger-coden/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/killbill%2Fkillbill-swagger-coden/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/killbill%2Fkillbill-swagger-coden/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/killbill","download_url":"https://codeload.github.com/killbill/killbill-swagger-coden/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239581802,"owners_count":19662958,"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":[],"created_at":"2024-11-07T13:12:23.912Z","updated_at":"2025-10-24T16:46:17.749Z","avatar_url":"https://github.com/killbill.png","language":"Mustache","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kill Bill Client Code Generation\n\nThis repository is an extension of the [swagger coden module](https://github.com/swagger-api/swagger-codegen#making-your-own-codegen-modules),\nand is used to generate our Kill Bill client libraries. It contains both a set of templates and java modules to allow to customize the generated client library.\n\n\nThe repo was generated using the [`meta` verb from the code generator](https://github.com/swagger-api/swagger-codegen#making-your-own-codegen-modules),\nand then tweaked by hand to fit our use case. This initial step should only be needed once.\n\n## Kill Bill Swagger Schema\n\nThe generator will require the Kill Bill swagger schema, and at this point we are using on swagger `1.5` (OA `2.0`).\nThe swagger schema can be obtained by hitting a running instance of Kill Bill:\n\n```\ncurl http://127.0.0.1:8080/swagger.json \u003e ./kbswagger.json \n```\n\nNote that we can also export yaml using:\n```\ncurl http://127.0.0.1:8080/swagger.yaml \u003e ./kbswagger.yaml \n```\n\n\nNote that there is some useful information about annotations in these pages.\n\n* [github wiki](https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X)\n* [swagger doc](https://swagger.io/docs/specification/2-0/)\n\n\n\n## Using the generator\n\n**Pre-requisite:** Read the [swagger README](https://github.com/swagger-api/swagger-codegen/blob/master/README.md) to install the binary and get some understanding on how things work. The generator relies on `swagger-codegen` version `2.4.1`. In order to download the `swagger-codegen-cli` required by the `build.sh` script, you can run the following (This downloads the `swagger-codegen-cli` jar file to the local Maven repo) :\n\n\n```\nmvn org.apache.maven.plugins:maven-dependency-plugin:2.8:get \\\n    -Dartifact=io.swagger:swagger-codegen-cli:2.4.1\n```\n\nNote that upgrading to `2.4.19`, latest patch version at the time of this writing led to incorrect code generation -- no further investigation was done, perhaps an easy fix -- but until we investigate we are stuck on this version.\n\n\nThe standard command to generate the code for `java` would be:\n\n```\nswagger-codegen  generate \\\n--invoker-package=\"client\" \\\n--api-package=\"api\" \\\n--model-package=\"models\" \\\n--http-user-agent=\"killbill/java-client\" \\\n--lang=java \\\n-i kbswagger.json \\\n-o ../killbill-client-java # Repo where to generate the code\n```\n\n## Using the build.sh script\n\nTo simplify the build process, this repo includes a [build.sh](https://github.com/killbill/killbill-swagger-coden/blob/a8de9958143f1954f53ff6634594e13f1c43909d/build.sh) script. We recommend that you use this script to build the client libraries. This script does the following:\n\n* Retrieves the KB version (requires a running instance of Kill Bill).\n* Retrieves the swagger spec (requires a running instance of Kill Bill).\n* Runs the generator.\n* Copies the `VERSION` file, under the client `.swagger-codegen` directory to keep track of the api against which this was generated.\n\nIn order to run this script, do the following:\n\n* Ensure that you have a running Kill Bill instance\n* Build this repo to generate the `killbill-swagger-codegen.jar` file as follows:\n\n        mvn clean install -DskipTests=true\n* Update `build.sh` as desired (You may need to update the `killbill-swagger-coden.jar` path, path of your local maven repo, etc.).\n* Run the script as follows (On Windows, you can use [Git Bash](https://git-scm.com/download/win) to run this script):\n\n        sh build.sh -l killbill-java -o ../killbill-client-java \n    \n* To generate the KB client code and wait for debugger to start on port 5005 use:\n\n\n        \u003e ./build.sh -l killbill-java -o ../killbill-client-java -w\n\n\n## Internals\n\nThe generator will rely on the swagger gen extensions to customize the code. For each supported language,\nwe will find a generator under the [languages package](https://github.com/killbill/killbill-swagger-coden/tree/master/src/main/java/org/killbill/billing/codegen/languages).\nThe customization is done by implementing/overriding methods from the [CodegenConfig](https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/main/java/io/swagger/codegen/CodegenConfig.java)\ninterface.\n\nThe code customization allows for the following:\n\n* Allows to define basic behavior (e.g generate tmestamp)\n* Allows to define mappings (e.g type mappings)\n* Allows to customize various input and output location (e.g output folder)\n* Allows to implement hooks during generation to customize the object map passed to the Mustache engine (e.g define variable that can be used during template execution)\n\nIn addition to code customization, we can also define our own Mustache templates to generate the client code we want to have.\n\nSo, in summary, the `kbswagger.json` input along with the custom code and templates provide a flexible way to generate client libraries in any language.\n\n## Modifying the generator\n\nModifying the generator, including the Mustache template would require building the repo: `mvn -DskipTests=true -Dmaven.javadoc.skip=true install`\n\n# Supported Languages\n\n## Java\n\nThere is a swagger module called `killbill-java`, that is used to generate the java client library. As explained earlier\nit consists of some templates and code module:\n\n* [KillbillJavaGenerator](https://github.com/killbill/killbill-swagger-coden/blob/master/src/main/java/org/killbill/billing/codegen/languages/KillbillJavaGenerator.java)\n* [killbill-java](https://github.com/killbill/killbill-swagger-coden/tree/master/src/main/resources/killbill-java) templates.\n\nThe code generation has been limited to generating model and api files, but at this point we have decided to reuse our existing http client, and reuse the mechanism we have in place, [RequestOptions](https://github.com/killbill/killbill-client-java/blob/killbill-client-java-0.41.7/src/main/java/org/killbill/billing/client/RequestOptions.java) --to pass additional headers through our apis.\n\nIn order to generate the Java client, use:\n\n```\nsh build.sh -l killbill-java -o ../killbill-client-java \n```\n\n\n## Python\n\nThere is a swagger module called `killbill-python`, that is used to generate the python client library.\n\n* [KillbillPythonGenerator](https://github.com/killbill/killbill-swagger-coden/blob/master/src/main/java/org/killbill/billing/codegen/languages/KillbillPythonGenerator.java)\n* [killbill-python](https://github.com/killbill/killbill-swagger-coden/tree/master/src/main/resources/killbill-python) templates.\n\n\nTo generate the client enter the following command:\n\n```sh\n\u003e ./build.sh -l killbill-python -o ../killbill-client-python\n```\nNote: If you don't want to generate the API docs, tests, and `git_push.hs` file just create a file named `.swagger-codegen-ignore` in the output directory.\nwith the following:\n```\ndocs/*.md\ntest/*\ngit_push.sh\n```\n[Reff: How to skip certain files during code generation?](https://github.com/swagger-api/swagger-codegen/wiki/FAQ#how-to-skip-certain-files-during-code-generation)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkillbill%2Fkillbill-swagger-coden","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkillbill%2Fkillbill-swagger-coden","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkillbill%2Fkillbill-swagger-coden/lists"}