{"id":15091315,"url":"https://github.com/networknt/openapi-bundler","last_synced_at":"2026-02-26T08:44:10.811Z","repository":{"id":33830835,"uuid":"153839607","full_name":"networknt/openapi-bundler","owner":"networknt","description":"A utility that merges multiple OpenAPI specification files into a single file with all external references resolved to local reference.","archived":false,"fork":false,"pushed_at":"2024-10-30T15:11:55.000Z","size":67,"stargazers_count":12,"open_issues_count":2,"forks_count":6,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-01-06T02:02:31.738Z","etag":null,"topics":["openapi","openapi-bundler","openapi-codegen","openapi-generator","openapi-spec","openapi-specification","openapi3","rest","rest-api"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/networknt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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-10-19T20:42:58.000Z","updated_at":"2025-01-05T14:16:27.000Z","dependencies_parsed_at":"2023-01-15T02:49:41.293Z","dependency_job_id":"da47250a-a8bd-4565-b6e0-9552cf7cd347","html_url":"https://github.com/networknt/openapi-bundler","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networknt%2Fopenapi-bundler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networknt%2Fopenapi-bundler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networknt%2Fopenapi-bundler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networknt%2Fopenapi-bundler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/networknt","download_url":"https://codeload.github.com/networknt/openapi-bundler/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248529756,"owners_count":21119576,"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":["openapi","openapi-bundler","openapi-codegen","openapi-generator","openapi-spec","openapi-specification","openapi3","rest","rest-api"],"created_at":"2024-09-25T10:40:21.403Z","updated_at":"2026-02-26T08:44:05.787Z","avatar_url":"https://github.com/networknt.png","language":"Java","readme":"# openapi-bundler\nA utility that merges multiple OpenAPI files into a single file with all external\nreferences resolved to local component references.\n\n## Why this OpenAPI Bundler\n\nOpenAPI is becoming the de-facto REST API specification, and a lot people have adopted it\nto write their RESTful API spec.\n\nFor small APIs, it is acceptable to have a single OpenAPI definition file, however for a large scale API\nproject, it is hard to manage multiple API specifications together.\n\nFor an organization with too\nmany APIs, it is very natural to define sharable object definitions in separate files\nin order to avoid duplications and foster consistency across an organization. With multiple files inter-connected together to form\none API specification, the directory structure and external references are too complicated\nto manage.\n\nLuckily, there are a lot of tools like editors, parsers and bundlers in the market that\nsupport multiple files. These tools can bundle multiple YAML files together to create\na final version in JSON or YAML format and de-reference external dependencies.\n\nAs our light-rest-4j framework encourages a contract driven design approach, the specification\nshould be created before coding starts. Actually, if the spec is ready, you can use\n[light-codegen](https://github.com/networknt/light-codegen) to generate the project.\n\nThe generator for [light-rest-4j](https://github.com/networknt/light-rest-4j)\ngenerates also the object model (POJO) from the openapi.json where objects are defined in the specification. In\naddition, light-rest-4j requires the final version of the openapi.json to be included\ninto the service code to do runtime schema validation as well as OAuth 2.0 scope\nverification at runtime.\n\nThis requires that the final version of openapi.json is self-contained and all models\nshould be defined in the components section instead of being de-referenced inline.\n\nExisting bundlers such as [swagger-cli](https://github.com/BigstickCarpet/swagger-cli)\ncannot handle our specification files correctly, therefore the need arises to create a generally re-usable bundler for OpenAPI definitions.\n\nThe tool validates bundled API specifications and offers also independent validation functionality.\n\n## Features\n\n### Remote Reference\n\nThis bundler can resolve all remote references in openapi.yaml which is the main file\nto be processed. If the reference is an object, it will resolve its internal references\nfirst and then move it into components in the generated openapi.json. At the same time\nthe external reference in openapi.yaml will be changed to local reference with #/components/{key}\n\nIf the remote reference is not an object, it will be resolved inline in the generated\nopenapi.json file.\n\nIf you have separate reference files, you must place these files into the same folder your openapi.yaml, or relative to that folder. For example, if you have common\nfolder that contains all the common OpenAPI files, you might need to copy the common\nfolder into your folder that contains openapi.yaml for your API.\n\n### Local Reference\n\nIf the reference is an object in components, it will resolve all the remote references\nin definitions.\n\nIf the reference is not an object, an error will occur and the process will exit.\n\n## Usage\n\nThe bundler assumes that the input file is openapi.yaml and all the remote reference files\nare in the right path.\n\n### Use it as Java utility\n\n```\njava -jar target/openapi-bundler.jar \u003coperation\u003e \u003carguments....\u003e\n\nOperations are:\n  bundle\n  validate\n\nArguments are:\n  --dir, -d : The input directory where the YAML files can be found for bundling | validation. Mandatory parameter\n  --file, -f : The name of the YAML file to be bundled or validated. Default: openapi.yaml\n\n  --outputFile, -of: The name of the bundled and validated OpenAPI file. Default: openapi.bundled\n  --outputDir, -od : The output directory of the bundled and validated file. Default: same as input directory specified in \u003cdir\u003e\n  --outputFormat, -o : TThe output format for the bundled file: YAML | JSON | both. Default: YAML\n\n  -debug : to view debug output\n\n# General usage:\n  Bundle: \n    java -jar openapi-bundler.jar bundle -d \u003cmyFolder\u003e -f \u003cinput file\u003e -o \u003cjson|yaml|both\u003e -of \u003coutput file name\u003e -od \u003coutput folder\u003e\n\n  Validate:\n    java -jar openapi-bundler.jar bundle -d \u003cmyFolder\u003e -f \u003cinput file\u003e\n\n# To view debug messages during the bundling or valdiation process, use the utility with -debug\n  java -debug -jar openapi-bundler.jar bundle -d \u003cmyFolder\u003e -f \u003cinput file\u003e -o \u003cjson|yaml|both\u003e \n\n# To view debug messages during the bundling or valdiation process, use the utility with -debug\n  java -debug -jar openapi-bundler.jar validate -d \u003cmyFolder\u003e -f \u003cinput file\u003e \n\n# Simplified bundler call, with default values, uses openapi.yaml as input and json as output format\njava -jar openapi-bundler.jar  bundle -d \u003cmyFolder\u003e\n\n\n```\n\nTo view usage help you can use the following command:\n```\nCommand:\njava -jar openapi-bundler.jar  -h\n\nUsage: [options] operation: The operation to be performed. \n       Supported operations: bundle |validate. Must be specified\n\n  Options:\n    --dir, -d\n      The input directory where the YAML files can be found. Must be specified\n    --file, -f\n      The name of the YAML file to be bundled. Default = openapi.yaml\n    --output, -o\n      The output format for the bundled file: yaml | json | both. Default = json\n      Default: json\n    --help, -h      \n    -debug\n      Debug mode\n      Default: false\n```\n### Sample files\nopenapi.yaml\n```\nopenapi: 3.0.0\n\npaths: \n  /test:\n    get:\n      operationId: test\n      responses:\n        '200':\n          content:\n            application/json:\n              schema:\n                type: array\n                items:\n                  $ref: 'common.yaml#/MyObj'\n```\n\ncommon.yaml\n```\nMyObj:\n  type: object\n  properties:\n    testCode:\n      type: string\n      readOnly: true\n    name:\n      type: string\n      readOnly: true\n```\n### Use it in an IDE\n\nAnother way to run the bundler is from an IDE. Just set the folder of the openapi.yaml file as a program argument and you can easily debug into it.\n\n### Use Docker\n\nThere is a Docker [image](https://hub.docker.com/r/networknt/openapi-bundler/) that is\npublished to Docker Hub.\n\nHere is the command line to call it.\n\n```\nTBD\n```\n\n\nWith above command line, you can easily build a script to call it as part of your DevOps\nflow.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetworknt%2Fopenapi-bundler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetworknt%2Fopenapi-bundler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetworknt%2Fopenapi-bundler/lists"}