{"id":28149869,"url":"https://github.com/insightsengineering/oasbinder","last_synced_at":"2025-06-14T19:32:33.284Z","repository":{"id":277352726,"uuid":"930405501","full_name":"insightsengineering/oasbinder","owner":"insightsengineering","description":"A tool to interact with OAS docs for multiple microservices","archived":false,"fork":false,"pushed_at":"2025-04-15T06:18:33.000Z","size":123,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-05-15T02:14:44.170Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://insightsengineering.github.io/oasbinder/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/insightsengineering.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"custom":["https://pharmaverse.org"]}},"created_at":"2025-02-10T15:28:03.000Z","updated_at":"2025-04-15T06:15:39.000Z","dependencies_parsed_at":"2025-02-13T14:25:01.017Z","dependency_job_id":"1553e425-13b5-4ce3-ae09-a4712f59650a","html_url":"https://github.com/insightsengineering/oasbinder","commit_stats":null,"previous_names":["insightsengineering/oasbinder"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/insightsengineering/oasbinder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightsengineering%2Foasbinder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightsengineering%2Foasbinder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightsengineering%2Foasbinder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightsengineering%2Foasbinder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/insightsengineering","download_url":"https://codeload.github.com/insightsengineering/oasbinder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insightsengineering%2Foasbinder/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259870758,"owners_count":22924586,"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":"2025-05-15T02:14:43.737Z","updated_at":"2025-06-14T19:32:33.262Z","avatar_url":"https://github.com/insightsengineering.png","language":"Go","funding_links":["https://pharmaverse.org"],"categories":[],"sub_categories":[],"readme":"# oasbinder\n\n[![build](https://github.com/insightsengineering/oasbinder/actions/workflows/test.yml/badge.svg)](https://github.com/insightsengineering/oasbinder/actions/workflows/test.yml)\n\n`oasbinder` is a utility which allows you to interact with multiple Swagger (OAS) docs for multiple microservices which can be defined in the [configuration file](#configuration-file).\n\nLet's assume we have the following service in the configuration file and the user accesses `oasbinder` at \u003chttps://oasbinder.example.com\u003e (`proxyAddress`).\n```yaml\nservices:\n  - endpoint: /hogwarts\n    url: http://host.docker.internal:8000/hogwarts/\n    swagger_url: http://localhost:8000/hogwarts/\n```\n\n* User can request the OAS docs for the microservice by going to `proxyAddress + endpoint` in the browser (in this example: \u003chttps://oasbinder.example.com/hogwarts\u003e).\n* `oasbinder` will request the OAS specification from the service at \u003chttp://host.docker.internal:8000/hogwarts/openapi.json\u003e and return it to the user for viewing and interacting in the browser.\n* When user interacts with the API in the browser, the requests to the API will be directed to \u003chttp://localhost:8000/hogwarts/\u003e.\n* In many cases `url` can be equal to `swagger_url`. An example of a situation where they can be different is e.g. a docker-compose setup where both `oasbinder` and the service can communicate via internal Docker network. `oasbinder` can request the OAS specs using the internal Docker hostname, and the user will send the requests using SwaggerUI to the service from the outside of the cluster via `swagger_url`.\n* The location of the OAS specs (`openapi.json` by default) is configurable. Multiple services can be configured and user can then select them from a drop-down list.\n* The drop-down list will contain the name and decription of the service retrieved from the OAS specs fields: `.info.title` and `.info.summary`.\n\nAll the services will need to have CORS configured in a way which allows requests from \u003chttps://oasbinder.example.com\u003e.\n\n\u003cimg src=\"images/oasbinder.png\" alt=\"oasbinder screenshot\" width=\"70%\"\u003e\n\n## Installing\n\nSimply download the project for your distribution from the [releases](https://github.com/insightsengineering/oasbinder/releases) page.\n`oasbinder` is distributed as a single binary file and does not require any additional system requirements.\n\nAlternatively, if you have a Go environment, you can simply install `oasbinder` by running:\n\n```shell\ngo install github.com/insightsengineering/oasbinder@latest\n```\n\nA helm chart is also available. You can install the `oasbinder` helm chart with:\n\n```bash\nhelm install oasbinder -f helm/templates/values.yaml oasbinder --repo https://insightsengineering.github.io/oasbinder/ --version 0.0.3 --namespace \u003cnamespace-name\u003e\n```\n\nExample `values.yaml` file is available in [helm/templates/values.yaml](helm/templates/values.yaml).\n\n## Usage\n\n`oasbinder` is a command line utility, so after installing the binary in your `PATH`, simply run the following command to view its capabilities:\n\n```bash\noasbinder --help\n```\n\n## Configuration file\n\nBy default `oasbinder` attempts to read `~/.oasbinder`, `~/.oasbinder.yaml` and `~/.oasbinder.yml` configuration files.\nIf any of these files exist, `oasbinder` uses options defined there, unless they are overridden by command line flags.\n\nYou can also specify custom path to configuration file with `--config \u003cyour-configuration-file\u003e.yml` command line flag.\n\nExample contents of configuration file:\n\n```yaml\n# The address at which the user will access `oasbinder`.\nproxyAddress: http://localhost:8080\n# The address on which `oasbinder` will listen.\nlistenAddress: 0.0.0.0\n# The port on which `oasbinder` will listen. This can be used in case `oasbinder` is run e.g. in a k8s cluster\n# and the user is accessing it from the outside of the cluster.\nlistenPort: 8080\n\nservices:\n  - endpoint: /gringotts\n    url: http://localhost:8000/gringotts/\n    swagger_url: http://localhost:8000/gringotts/\n  - endpoint: /hogwarts\n    url: http://localhost:8000/hogwarts/\n    swagger_url: http://localhost:8000/hogwarts/\n\n# Additional headers to pass to microservices, e.g. for authentication.\nheaders:\n  api-key: qwerty\n```\n\n## Environment variables\n\n`oasbinder` reads environment variables with `OASBINDER_` prefix and tries to match them with CLI flags.\nFor example, setting the following variables will override the respective value from the configuration file: `OASBINDER_LOGLEVEL` etc.\n\nThe order of precedence is:\n\nCLI flag → environment variable → configuration file → default value.\n\nTo check the available names of environment variables, please run `oasbinder --help`.\n\n## Development\n\nThis project is built with the [Go programming language](https://go.dev/).\n\n### Development Environment\n\nIt is recommended to use Go 1.23+ for developing this project.\nThis project uses a pre-commit configuration and it is recommended to [install and use pre-commit](https://pre-commit.com/#install) when you are developing this project.\n\n### Common Commands\n\nRun `make help` to list all related targets that will aid local development.\n\n## License\n\n`oasbinder` is licensed under the Apache 2.0 license. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsightsengineering%2Foasbinder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finsightsengineering%2Foasbinder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsightsengineering%2Foasbinder/lists"}