{"id":14986556,"url":"https://github.com/maxdome/swagger-combine","last_synced_at":"2025-04-04T20:14:45.757Z","repository":{"id":20685185,"uuid":"90612259","full_name":"maxdome/swagger-combine","owner":"maxdome","description":"Combines multiple Swagger schemas into one dereferenced schema.","archived":false,"fork":false,"pushed_at":"2023-01-24T06:04:41.000Z","size":302,"stargazers_count":135,"open_issues_count":34,"forks_count":37,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-28T19:09:33.733Z","etag":null,"topics":["api","documentation","hacktoberfest","open-api","openapi","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/maxdome.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":"2017-05-08T09:48:08.000Z","updated_at":"2025-01-10T03:03:45.000Z","dependencies_parsed_at":"2023-02-13T18:20:44.845Z","dependency_job_id":null,"html_url":"https://github.com/maxdome/swagger-combine","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxdome%2Fswagger-combine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxdome%2Fswagger-combine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxdome%2Fswagger-combine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxdome%2Fswagger-combine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxdome","download_url":"https://codeload.github.com/maxdome/swagger-combine/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247242680,"owners_count":20907134,"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","documentation","hacktoberfest","open-api","openapi","swagger"],"created_at":"2024-09-24T14:13:08.268Z","updated_at":"2025-04-04T20:14:45.738Z","avatar_url":"https://github.com/maxdome.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Swagger Combine\n===============\n\n[![Build Status](https://img.shields.io/github/workflow/status/maxdome/swagger-combine/Node.js%20CI/master.svg)](https://github.com/maxdome/swagger-combine/actions?query=workflow%3A%22Node.js+CI%22)\n[![Coverage Status](https://coveralls.io/repos/github/maxdome/swagger-combine/badge.svg?branch=master)](https://coveralls.io/github/maxdome/swagger-combine?branch=master)\n[![dependencies Status](https://david-dm.org/maxdome/swagger-combine/status.svg)](https://david-dm.org/maxdome/swagger-combine)\n[![devDependencies Status](https://david-dm.org/maxdome/swagger-combine/dev-status.svg)](https://david-dm.org/maxdome/swagger-combine?type=dev)\n[![npm](https://img.shields.io/npm/v/swagger-combine.svg)](https://www.npmjs.com/package/swagger-combine)\n\n\u003eCombines multiple Swagger schemas into one dereferenced schema.\n\n## Install\n\n```sh\n$ npm install --save swagger-combine\n```\n\n#### Globally for CLI usage\n\n```sh\n$ npm install -g swagger-combine\n```\n\n## Usage\n\n```js\nconst swaggerCombine = require('swagger-combine');\n\nswaggerCombine('docs/swagger.json')\n    .then(res =\u003e console.log(JSON.stringify(res)))\n    .catch(err =\u003e console.error(err));\n```\n\n**Swagger Combine** returns a promise by default. Alternatively a callback can be passed as second argument:\n\n```js\nswaggerCombine('docs/swagger.json', (err, res) =\u003e {\n  if (err) console.error(err);\n  else console.log(JSON.stringify(res));\n});\n```\n\n### Middleware\n\n```js\nconst swaggerCombine = require('swagger-combine');\nconst app = require('express')();\n\napp.get('/swagger.json', swaggerCombine.middleware('docs/swagger.json'));\napp.get('/swagger.yaml', swaggerCombine.middleware('docs/swagger.json', { format: 'yaml' }));\napp.listen(3333);\n```\n\nThe middleware runs the combine function on every request. Since Swagger documentations tend not to change that frequently, the use of a caching mechanism like [apicache](https://github.com/kwhitley/apicache) is encouraged in conjungtion with this middleware.\n\n### Async Middleware\n\n```js\nconst swaggerCombine = require('swagger-combine');\nconst app = require('express')();\n\n(async function() {\n  try {\n    app.get('/swagger.json', await swaggerCombine.middlewareAsync('docs/swagger.json'));\n    app.get('/swagger.yaml', await swaggerCombine.middlewareAsync('docs/swagger.json', { format: 'yaml' }));\n  } catch (e) {\n    console.error(e);\n  }\n\n  app.listen(3333);\n})();\n\n```\n\n### CLI\n\n```sh\n$ swagger-combine config.json\n```\n\n#### Help\n\n```sh\n$ swagger-combine -h\n```\n\n#### Save to File\n\n```sh\n$ swagger-combine config.json -o combinedSchema.json\n```\n\n#### YAML Output\n\nThe output is in YAML if the output filename ends with `.yaml` or `.yml`:\n\n```sh\n$ swagger-combine config.json -o combinedSchema.yaml\n```\n\nAlternatively the `--format` or `-f` argument can be used:\n\n```sh\n$ swagger-combine config.json -f yaml\n```\n\n## Configuration\n\n* **Swagger Combine** requires one configuration schema which resembles a standard Swagger schema except for an additional `apis` field.\n* Since this module uses [Swagger Parser](https://github.com/BigstickCarpet/swagger-parser) and [JSON Schema $Ref Parser](https://github.com/BigstickCarpet/json-schema-ref-parser) internally the schema can be passed to **Swagger Combine** as a file path, a URL or a JS object.\n* All `$ref` fields in the configuration schema are getting dereferenced.\n* The default path for the configuration file is `docs/swagger.json`.\n* The configuration file can be `JSON` or `YAML`.\n\n### Basic Configuration\n\n**swagger.json**\n\n```json\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"Basic Swagger Combine Example\",\n    \"version\": \"1.0.0\"\n  },\n  \"apis\": [\n    {\n      \"url\": \"http://petstore.swagger.io/v2/swagger.json\"\n    },\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml\"\n    },\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/deutschebahn.com/betriebsstellen/v1/swagger.json\",\n      \"paths\": {\n        \"base\": \"/bahn\"\n      }\n    }\n  ]\n}\n```\n\n**swagger.yaml**\n\n```yaml\nswagger: '2.0'\ninfo:\n  title: Basic Swagger Combine Example\n  version: 1.0.0\napis:\n  - url: 'http://petstore.swagger.io/v2/swagger.json'\n  - url: 'https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml'\n  - url: 'https://api.apis.guru/v2/specs/deutschebahn.com/betriebsstellen/v1/swagger.json'\n    paths:\n      base: '/bahn'\n```\n\n*All example configurations are located in the `examples` folder.*\n\n\n### Filtering Paths\n\nPaths can be filtered by using an array of paths and regex strings to `exclude` or `include`.\n\n```json\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"Swagger Combine Filter Example\",\n    \"version\": \"1.0.0\"\n  },\n  \"apis\": [\n    {\n      \"url\": \"http://petstore.swagger.io/v2/swagger.json\",\n      \"paths\": {\n        \"exclude\": [\n          \"/pet/{petId}\",\n          \"/pet.put\"\n        ]\n      }\n    },\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml\",\n      \"paths\": {\n        \"include\": [\n          \"/users/{userId}/publications\",\n          \"/me.get\"\n        ]\n      }\n    }\n  ]\n}\n```\n\nExample of using Regex Strings (in combination with path string)\n\n```json\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"Swagger Combine Filter Example\",\n    \"version\": \"1.0.0\"\n  },\n  \"apis\": [\n    {\n      \"url\": \"http://petstore.swagger.io/v2/swagger.json\",\n      \"paths\": {\n        \"exclude\": [\n          \".*\\{petId\\}.get\"\n        ]\n      }\n    },\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml\",\n      \"paths\": {\n        \"include\": [\n          \".*?/publications(/.*)?\",\n          \"/me.get\"\n        ]\n      }\n    }\n  ]\n}\n```\n\n### Filtering Parameters\n\nParameters can be filtered by specifying the path and the parameter name as to `exclude` or `include` as key/value pairs in `paths.parameters`.\n\n```json\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"Swagger Combine Filter Example\",\n    \"version\": \"1.0.0\"\n  },\n  \"apis\": [\n    {\n      \"url\": \"http://petstore.swagger.io/v2/swagger.json\",\n      \"paths\": {\n        \"parameters\": {\n          \"exclude\": {\n            \"/pet/findByStatus\": \"status\"\n          }\n        }\n      }\n    },\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml\",\n      \"paths\": {\n        \"include\": [\n          \"/users/{userId}/publications\",\n          \"/publications/{publicationId}/posts\",\n          \"/me.get\"\n        ],\n        \"parameters\": {\n          \"include\": {\n            \"/publications/{publicationId}/posts.post\": \"publicationId\"\n          }\n        }\n      }\n    }\n  ]\n}\n```\n\n### Base Path\n\nThe base path for each Swagger schema can be set by `base`:\n\n```json\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"Basic Swagger Combine Example\",\n    \"version\": \"1.0.0\"\n  },\n  \"apis\": [\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml\"\n    },\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/deutschebahn.com/betriebsstellen/v1/swagger.json\",\n      \"paths\": {\n        \"base\": \"/bahn\"\n      }\n    }\n  ]\n}\n```\n\nBase path definition in Swagger schemas is ignored by default and the processing can be enabled individually by setting `useBasePath`. When enabled, the base path and path information is combinded during processing. The option can also be enabled in general (see below). If `base` is set, the `useBasePath` is ignored. \n\n```json\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"Swagger Combine simple Rename Example\",\n    \"version\": \"1.0.0\"\n  },\n  \"apis\": [\n    {\n      \"url\": \"http://petstore.swagger.io/v2/swagger.json\",\n      \"paths\": {\n        \"useBasePath\": true\n      }\n    },\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml\"\n    }\n  ]\n}\n```\n\n### Renaming Paths\n\nPaths can be renamed by specifying the path to rename and the new path name as key/value pairs in `paths.rename`.\nThis will replace each key matched by path with the new value. \n\n```json\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"Swagger Combine simple Rename Example\",\n    \"version\": \"1.0.0\"\n  },\n  \"apis\": [\n    {\n      \"url\": \"http://petstore.swagger.io/v2/swagger.json\",\n      \"paths\": {\n        \"rename\": {\n          \"/pet/{petId}\": \"/pet/alive/{petId}\"\n        }\n      }\n    },\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml\"\n    }\n  ]\n}\n```\n\nPaths can also be replaced by regular expressions and functions.\n\nTo configure this, it's necessary to use an array like structure instead of an object with key/value pairs to ensure the order of replacements.\n\nIn the `swagger.json` file only \"renaming\" and/or a string like regular expression can be used. For regular expression objects or functions the (swagger)json configuration must be generated by javascript and used as input parameter of the swaggerCombine function.\n\nThe next example equals the simple example above but used an extended configuration style.\n\n```json\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"Swagger Combine simple Rename Example\",\n    \"version\": \"1.0.0\"\n  },\n  \"apis\": [\n    {\n      \"url\": \"http://petstore.swagger.io/v2/swagger.json\",\n      \"paths\": {\n        \"rename\": [\n          { \n            \"type\": \"rename\",\n            \"from\": \"/pet/{petId}\",\n            \"to\": \"/pet/alive/{petId}\"\n          } \n        ]\n      }\n    },\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml\"\n    }\n  ]\n}\n```\n\nTo change the basePath of all paths a regular expression can be used.\n\n```json\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"Swagger Combine Rename by regular expression Example\",\n    \"version\": \"1.0.0\"\n  },\n  \"apis\": [\n    {\n      \"url\": \"http://petstore.swagger.io/v2/swagger.json\",\n      \"paths\": {\n        \"rename\": [\n          { \n            \"type\": \"regex\",\n            \"from\": \"^\\/pet\\/(.*)\",\n            \"to\": \"/pet/alive/$1\"\n          } \n        ]\n      }\n    },\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml\"\n    }\n  ]\n}\n```\n\nAn example of dynamic generated configuration and renamings with regular expressions and functions. \n\n```javascript\nconst swaggerJson = {\n  swagger: \"2.0\",\n  info: {\n    title: \"Swagger Combine Rename by regular expression Example\",\n    version: \"1.0.0\"\n  },\n  apis: [\n    {\n      url: \"http://petstore.swagger.io/v2/swagger.json\",\n      paths: {\n        rename: [\n          { \n            type: \"regex\",\n            from: /\\/pet\\/(.*)/,\n            to: \"/pet/alive/$1\"\n          },\n          { \n            type: \"function\",\n            to: (path) =\u003e path === \"/pet/alive/{petId}\" ? \"/pet/alive/{petAliveId}\" : path\n          }\n        ]\n      }\n    },\n    {\n      url: \"https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml\"\n    }\n  ]\n}\n\nswaggerCombine(swaggerJson)\n...\n```\n\n### Renaming Tags\n\nTags can be renamed in the same manner as paths with simple, object like configuration style, using the `tags.rename` field.\n\n```json\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"Swagger Combine Rename Example\",\n    \"version\": \"1.0.0\"\n  },\n  \"apis\": [\n    {\n      \"url\": \"http://petstore.swagger.io/v2/swagger.json\"\n    },\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml\",\n      \"tags\": {\n        \"rename\": {\n          \"Users\": \"People\"\n        }\n      }\n    }\n  ]\n}\n```\n\n### Renaming Path OperationIds\n\nWhen merging different swagger definitions there are situations were the operationIds used in these separate swaggers could collide. If this is the case and changing source isn't desired or possible. OperationIds can be renamed by specifying the existing id to rename and the new id as key/value pairs in `operationIds.rename`.\n\nThis will replace each operationId matched by the provided key with the new value.\n\n```json\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"Swagger Combine Simple OperationId Rename Example\",\n    \"version\": \"1.0.0\"\n  },\n  \"apis\": [\n    {\n      \"url\": \"http://petstore.swagger.io/v2/swagger.json\",\n      \"operationIds\": {\n        \"rename\": {\n          \"addPet\": \"createPet\"\n        }\n      }\n    },\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml\"\n    }\n  ]\n}\n```\n\n### Adding Tags\n\nTags can be added to all operations in a schema, using the `tags.add` field.\n\n```json\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"Swagger Combine Rename Example\",\n    \"version\": \"1.0.0\"\n  },\n  \"apis\": [\n    {\n      \"url\": \"http://petstore.swagger.io/v2/swagger.json\",\n      \"tags\": {\n        \"add\": [\n          \"pet\"\n        ]\n      }\n    },\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml\",\n      \"tags\": {\n        \"add\": [\n          \"medium\"\n        ]\n      }\n    }\n  ]\n}\n```\n\n### Renaming Security Definitions\n\nSecurity definitions can be renamed like paths (simple) and tags in the `securityDefinitions.rename` field. All usages of the security definition in the paths are renamed as well.\n\n```json\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"Swagger Combine Rename Example\",\n    \"version\": \"1.0.0\"\n  },\n  \"apis\": [\n    {\n      \"url\": \"http://petstore.swagger.io/v2/swagger.json\",\n      \"securityDefinitions\": {\n        \"rename\": {\n          \"api_key\": \"KEY\"\n        }\n      }\n    },\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml\"\n    }\n  ]\n}\n```\n\n### Path Security\n\nSecurity can be specified per path using the `paths.security` field.\n\n```json\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"Swagger Combine Security Example\",\n    \"version\": \"1.0.0\"\n  },\n  \"apis\": [\n    {\n      \"url\": \"http://petstore.swagger.io/v2/swagger.json\",\n      \"paths\": {\n        \"security\": {\n          \"/store/order\": {\n            \"petstore_auth\": [\n              \"write:pets\",\n              \"read:pets\"\n            ]\n          },\n          \"/store/order/{orderId}.delete\": {\n            \"petstore_auth\": [\n               \"write:pets\",\n               \"read:pets\"\n             ]\n          }\n        }\n      }\n    },\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml\"\n    }\n  ]\n}\n```\n\n### Authentication \u0026 Request Headers\n\nTo retrieve Swagger schemas that are access protected, basic auth information (username and password) or any headers to be sent with the http request can be specified:\n\n```json\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"Swagger Combine Authentication Example\",\n    \"version\": \"1.0.0\"\n  },\n  \"apis\": [\n    {\n      \"url\": \"http://petstore.swagger.io/v2/swagger.json\",\n      \"resolve\": {\n        \"http\": {\n          \"auth\": {\n            \"username\": \"admin\",\n            \"password\": \"secret12345\"\n          }\n        }\n      }\n    },\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/medium.com/1.0.0/swagger.yaml\",\n      \"resolve\": {\n        \"http\": {\n          \"headers\": {\n            \"authorization\": \"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6ImFkbWluIiwiYWRtaW4iOnRydWV9.44lJS0jlltzcglq7vgjXMXYRTecBxseN3Dec_LO_osI\"\n          }\n        }\n      }\n    },\n    {\n      \"url\": \"https://api.apis.guru/v2/specs/deutschebahn.com/betriebsstellen/v1/swagger.json\",\n      \"resolve\": {\n        \"http\": {\n          \"headers\": {\n            \"authorization\": \"Basic YWRtaW46c2VjcmV0MTIz\"\n          }\n        }\n      }\n    }\n  ]\n}\n```\n\nFor all possible resolve options have a look at the [documentation of json-schema-ref-parser](https://github.com/BigstickCarpet/json-schema-ref-parser/blob/master/docs/options.md#resolve-options).\n\n\n## API\n\n### swaggerCombine(config, [options], [callback])\n\n**Returns** `promise` with dereferenced and combined schema.\n\n#### config `string|object`\n\n\u003e URL/path to config schema file or config schema object.\n\u003e\n\u003e **Default:** `docs/swagger.json`\n\n#### options `object` *(optional)*\n\n* **format** - `string`\n\n    Content type of the response. `yaml` or `json` *(default)*.\n\n* **continueOnError** - `boolean`\n\n    Continue if Swagger configs cannot be resolved or are invalid (default: `false`). *No warning or error message is returned if this option is enabled.*\n\n* **continueOnConflictingPaths** - `boolean`\n\n    Continue if Swagger schemas have conflicting paths (default: `false`). An error is only thrown if conflicting paths also have conflicting operations (e.g. if two Swagger schemas both have `/pets.get` and `/pets.get` defined).\n\n\u003e See [JSON Schema $Ref Parser Options](https://github.com/BigstickCarpet/json-schema-ref-parser/blob/master/docs/options.md) for a complete list of options.\n\n* **useBasePath** - `boolean` *(default: false)*\n\n    The base path defintion in Swagger schemas is ignored by default. To respect the base path during combination, configure `useBasePath` in general or for individual Swagger schemas.\n\n* **includeGlobalTags** - `boolean` *(default: false)*\n\n    Combine global tags (set on the root level of the schemas) as well.\n\n#### callback `function(err, combinedSchema)` *(optional)*\n\n\u003e Callback with error and the dereferenced and combined schema.\n\n\n### swaggerCombine.middleware(config, [options])\n\n**Returns** `function(req, res, next)` for usage as middleware.\n\n#### config `string|object`\n\n*see above*\n\n#### options `object` *(optional)*\n\n*see above*\n\n### swaggerCombine.middlewareAsync(config, [options])\n\n**Returns** a `promise` yielding a `function(req, res, next)` for usage as middleware.\n\n#### config `string|object`\n\n*see above*\n\n#### options `object` *(optional)*\n\n*see above*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxdome%2Fswagger-combine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxdome%2Fswagger-combine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxdome%2Fswagger-combine/lists"}