{"id":17044,"library":"openapi-merge-cli","title":"OpenAPI Merge CLI","description":"The `openapi-merge-cli` package provides a command-line interface for merging multiple OpenAPI 3.0 specification files into a single, consolidated specification. It is built upon the `openapi-merge` library, inheriting its core merging algorithm. The tool is currently at version 1.3.2 and appears to be actively maintained in sync with its underlying library. Its primary use case is consolidating specifications from various microservices for exposure behind a single API Gateway, offering features like robust conflict resolution for component names, flexible path modification (stripping or prepending segments), and granular operation selection based on tags. It also supports merging `info.description` fields with custom titles. Unlike many general-purpose OpenAPI tools, its feature set is specifically tailored for API Gateway integration scenarios.","status":"active","version":"1.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/robertmassaioli/openapi-merge","tags":["javascript","openapi","merge","cli"],"install":[{"cmd":"npm install openapi-merge-cli","lang":"bash","label":"npm"},{"cmd":"yarn add openapi-merge-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add openapi-merge-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the core OpenAPI merging logic and algorithm.","package":"openapi-merge","optional":false}],"imports":[{"note":"This package is a command-line interface tool and is not typically imported into JavaScript/TypeScript code. 'npx' is the primary way to execute it without global installation.","wrong":"openapi-merge-cli","symbol":"openapi-merge-cli command","correct":"npx openapi-merge-cli"},{"note":"For environments where frequent use or PATH integration is desired. Local installation requires 'npx' or a 'package.json' script.","wrong":"npm install openapi-merge-cli && openapi-merge-cli","symbol":"Global Installation","correct":"npm install -g openapi-merge-cli && openapi-merge-cli"},{"note":"The tool defaults to 'openapi-merge.json' in the current directory. Use '--config' to specify an alternative path or filename.","wrong":"openapi-merge-cli","symbol":"Configuration File (openapi-merge.json)","correct":"openapi-merge-cli --config ./path/to/my-custom-config.json"}],"quickstart":{"code":"const fs = require('fs');\nconst path = require('path');\nconst { execSync } = require('child_process');\n\nconst configPath = path.join(__dirname, 'openapi-merge.json');\nconst outputPath = path.join(__dirname, 'output.swagger.json');\n\nconst config = {\n  \"inputs\": [\n    { \"inputFile\": \"./service-a.swagger.json\" },\n    {\n      \"inputFile\": \"./service-b.swagger.yaml\",\n      \"pathModification\": { \"prepend\": \"/api/v2\" },\n      \"operationSelection\": { \"includeTags\": [\"public\"] }\n    }\n  ],\n  \"output\": outputPath\n};\n\n// Dummy OpenAPI input files for demonstration\nconst serviceA = `{\n  \"openapi\": \"3.0.0\",\n  \"info\": { \"title\": \"Service A\", \"version\": \"1.0.0\" },\n  \"paths\": {\n    \"/health\": {\n      \"get\": {\n        \"summary\": \"Health check A\",\n        \"responses\": { \"200\": { \"description\": \"OK\" } }\n      }\n    }\n  }\n}`;\n\nconst serviceB = `\nopenapi: 3.0.0\ninfo:\n  title: Service B\n  version: 1.0.0\npaths:\n  /users:\n    get:\n      tags:\n        - public\n      summary: List users B\n      responses:\n        '200':\n          description: OK\n  /admin:\n    get:\n      tags:\n        - private\n      summary: Admin endpoint B\n      responses:\n        '200':\n          description: OK\n`;\n\ntry {\n  // Create dummy input files and configuration file\n  fs.writeFileSync(path.join(__dirname, 'service-a.swagger.json'), serviceA);\n  fs.writeFileSync(path.join(__dirname, 'service-b.swagger.yaml'), serviceB);\n  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));\n\n  console.log('Created openapi-merge.json and dummy input files.');\n  console.log('Running openapi-merge-cli...');\n\n  // Execute the CLI tool using npx\n  execSync(`npx openapi-merge-cli --config ${configPath}`, { stdio: 'inherit' });\n\n  console.log(`OpenAPI specification merged to ${outputPath}`);\n  console.log('You can now inspect output.swagger.json');\n\n  // Optional: Clean up generated files\n  // fs.unlinkSync(configPath);\n  // fs.unlinkSync(path.join(__dirname, 'service-a.swagger.json'));\n  // fs.unlinkSync(path.join(__dirname, 'service-b.swagger.yaml'));\n} catch (error) {\n  console.error('Failed to merge OpenAPI files:', error.message);\n  process.exit(1);\n}","lang":"javascript","description":"This quickstart demonstrates how to programmatically set up an 'openapi-merge.json' configuration and input files, then execute the 'openapi-merge-cli' tool using Node.js to merge them."},"warnings":[{"fix":"Ensure all input files conform strictly to OpenAPI 3.0.x. Use conversion tools or manual updates if working with older specifications.","message":"The tool exclusively supports OpenAPI Specification 3.0.x. Older versions, such as OpenAPI 2.0 (Swagger), are not compatible and will result in parsing errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Design your `stripStart` and `prepend` values with this fixed order in mind. For example, if you want '/v1/users' to become '/api/v2/users', strip '/v1' then prepend '/api/v2'.","message":"When configuring `pathModification` for an input, the `stripStart` option is always applied before `prepend`. This deterministic order prevents unexpected path structures.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Carefully review tag definitions to ensure desired operations are included. Avoid conflicting include/exclude rules for the same operation or adjust your tagging strategy.","message":"If an operation has both `operationSelection.includeTags` and `operationSelection.excludeTags` defined, the `excludeTags` rule will always take precedence, ensuring the operation is omitted from the merged output.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use the `dispute.prefix` or `dispute.suffix` options within the relevant input entry in your `openapi-merge.json` configuration to automatically rename conflicting components.","message":"When component names (e.g., schemas, parameters) conflict between multiple input OpenAPI files, `openapi-merge-cli` requires explicit dispute resolution via the `dispute` configuration for that input to prevent unexpected overwrites or errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Create an `openapi-merge.json` file in your project root or specify its correct path using `openapi-merge-cli --config ./path/to/my-config.json`.","cause":"The `openapi-merge.json` file is missing in the current working directory or the specified path via `--config` is incorrect.","error":"Error: No configuration file found at 'openapi-merge.json'. Please create one or specify a path with --config."},{"fix":"Verify that all `inputFile` and `inputURL` paths in your `openapi-merge.json` configuration are correct, accessible, and exist.","cause":"An `inputFile` or `inputURL` specified in the `openapi-merge.json` configuration does not point to an existing or accessible file/URL.","error":"Input file './missing-service.yaml' not found. Please check the path configured in openapi-merge.json."},{"fix":"Add a `dispute` object (e.g., `{\"prefix\": \"MyService\"}`) to the relevant input entry in `openapi-merge.json` to automatically rename conflicting components.","cause":"Two or more input OpenAPI files define a component (e.g., a schema, parameter, response) with the exact same name, and no `dispute` resolution strategy is configured for the conflicting input.","error":"Error: Component 'MySchema' already exists. Use the 'dispute' option in your configuration to resolve conflicts."},{"fix":"Validate all input OpenAPI files against the OpenAPI 3.0 schema using a linter or validator (e.g., 'spectral lint') to identify and correct any structural issues.","cause":"One of the provided input files is not a valid OpenAPI 3.0 specification, often due to missing top-level required fields or general malformation.","error":"Invalid OpenAPI specification: missing required field 'openapi'"}],"ecosystem":"npm","meta_description":null}