{"id":14986729,"url":"https://github.com/kota65535/openapi-merger","last_synced_at":"2025-04-06T10:12:32.218Z","repository":{"id":39625883,"uuid":"275802208","full_name":"kota65535/openapi-merger","owner":"kota65535","description":"Merges multiple OpenAPI document files into a single file.","archived":false,"fork":false,"pushed_at":"2025-03-23T15:01:18.000Z","size":297,"stargazers_count":32,"open_issues_count":15,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-27T00:08:52.922Z","etag":null,"topics":["openapi","openapi3","swagger"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kota65535.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-29T12:02:45.000Z","updated_at":"2024-12-06T02:01:42.000Z","dependencies_parsed_at":"2024-02-04T07:25:10.842Z","dependency_job_id":"0ccb613c-bee7-4142-a4fc-79e4d130b78c","html_url":"https://github.com/kota65535/openapi-merger","commit_stats":{"total_commits":117,"total_committers":6,"mean_commits":19.5,"dds":0.4273504273504274,"last_synced_commit":"cae508b47d97ee55f8607751a49914c21342a79a"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kota65535%2Fopenapi-merger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kota65535%2Fopenapi-merger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kota65535%2Fopenapi-merger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kota65535%2Fopenapi-merger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kota65535","download_url":"https://codeload.github.com/kota65535/openapi-merger/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247464222,"owners_count":20942970,"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","openapi3","swagger"],"created_at":"2024-09-24T14:13:25.773Z","updated_at":"2025-04-06T10:12:32.188Z","avatar_url":"https://github.com/kota65535.png","language":"JavaScript","funding_links":[],"categories":["\u003ca name=\"JavaScript\"\u003e\u003c/a\u003eJavaScript"],"sub_categories":[],"readme":"# openapi-merger\n\nYet another CLI tool for merging multiple OpenAPI files into a single file.\n\n![build workflow](https://github.com/kota65535/openapi-merger/actions/workflows/build.yml/badge.svg)\n[![NPM](https://nodei.co/npm/openapi-merger.png)](https://nodei.co/npm/openapi-merger/)\n\n## Features\n- Similar to [swagger-merger](https://github.com/WindomZ/swagger-merger)\n- Convert all remote \u0026 URL refs into local refs\n  - This is useful on code generation, because it helps [openapi-generator](https://github.com/OpenAPITools/openapi-generator)\n    to output unique model classes without duplication.\n- `$include` keyword: same as `$ref`, except it merges the object with sibling elements. (`$ref` ignores them)\n\n## Usage\n\n```sh\n$ npm install -g openapi-merger\n$ openapi-merger -i openapi.yaml -o merged.yaml\n```\n\n## $include keyword\n\nopenapi-merger introduces the special keyword `$include`.\nIt has similar syntax as `$ref`, which takes JSON reference as its value.\n\n```yaml\n$include: 'reference to content'\n```\n\nThe biggest difference is that `$include` replaces itself directly by the referenced content, allowing to merge its sibling elements.\n\n\n### Merge objects \u0026 arrays\n\nIf `$include` is used in an object and then referenced content is an object too, they are merged.\n\n- main.yml\n```yaml\nobject:\n  $include: object.yml\n  key3: val3\n```\n\n- object.yml\n```yaml\nkey1: val1\nkey2: val2\n```\n\n- results in:\n```yaml\nobject:\n  key1: val1\n  key2: val2\n  key3: val3\n``` \n\nArrays go in the same manner.\n\n- main.yml\n```yaml\narray:\n  - $include: array.yml\n  - val3\n```\n\n- array.yml\n```yaml\n- val1\n- val2\n```\n\n- results in:\n```yaml\narray:\n  - val1\n  - val2\n  - val3\n``` \n\nIf you want not to merge arrays, use `$include` in a nested array.\n\n- main.yml\n```yaml\narray:\n  - - $include: array.yml\n  - val3\n```\n\n- array.yml\n```yaml\n- val1\n- val2\n```\n\n- results in:\n```yaml\narray:\n  - - val1\n    - val2\n  - val3\n``` \n\n### Multiple $include at same place\n\n`$include` can be used multiple times in the same place by appending `#` with some ID, avoiding key duplication.\n\n```yaml\n$include#foo: ./foo.yml\n$include#bar: ./bar.yml\n```\n\n\n### Key modification \u0026 Filtering\n\n`$include` is capable of modification and filtering of the keys of the referenced content.\nThis is useful when you want to aggregate multiple OpenAPI documents of backend services into one for API Gateway.\n\nTo utilize this function, a configuration file should be given by `-c` option.\nThe configuration file is like following:\n\n```yaml\ninclude:\n  # 'foo' class, which add '/v1' prefix to each key\n  foo:\n    prefix: /v1\n  # 'bar' class, which selects only keys matching to regex \n  # here excluding paths that begins 'internal'\n  bar: \n    filter: ^(?!/internal).*\n```\n\nUse defined class as following:\n- main.yml\n```yaml\n# using foo class\n$include.foo: paths.yml \n# using bar class\n$include.bar: paths.yml\n```\n\n- paths.yml\n```yaml\n/users:\n  post:\n    ...\n\n/users/{id}:\n  get:\n    ...\n\n/internal/pets:\n  post:\n    ...\n```\n\n- results in:\n```yaml\n# from $include.foo\n/v1/users:\n  post:\n    ...\n\n/v1/users/{id}:\n  get:\n    ...\n\n/v1/internal/pets:\n  post:\n    ...\n\n# from $include.bar\n/users:\n  post:\n    ...\n\n/users/{id}:\n  get:\n    ...\n```\n\nYou can still use `#` notation to avoid key conflicts like below. \n\n```yaml\n$include#a.foo: paths1.yml\n$include#b.foo: paths2.yml\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkota65535%2Fopenapi-merger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkota65535%2Fopenapi-merger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkota65535%2Fopenapi-merger/lists"}