Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
openapi-merge-cli command
✓ npx openapi-merge-cli
✗ openapi-merge-cli
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.
Global Installation
✓ npm install -g openapi-merge-cli && openapi-merge-cli
✗ npm install openapi-merge-cli && openapi-merge-cli
For environments where frequent use or PATH integration is desired. Local installation requires 'npx' or a 'package.json' script.
Configuration File (openapi-merge.json)
✓ openapi-merge-cli --config ./path/to/my-custom-config.json
✗ openapi-merge-cli
The tool defaults to 'openapi-merge.json' in the current directory. Use '--config' to specify an alternative path or filename.
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.
const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');
const configPath = path.join(__dirname, 'openapi-merge.json');
const outputPath = path.join(__dirname, 'output.swagger.json');
const config = {
"inputs": [
{ "inputFile": "./service-a.swagger.json" },
{
"inputFile": "./service-b.swagger.yaml",
"pathModification": { "prepend": "/api/v2" },
"operationSelection": { "includeTags": ["public"] }
}
],
"output": outputPath
};
// Dummy OpenAPI input files for demonstration
const serviceA = `{
"openapi": "3.0.0",
"info": { "title": "Service A", "version": "1.0.0" },
"paths": {
"/health": {
"get": {
"summary": "Health check A",
"responses": { "200": { "description": "OK" } }
}
}
}
}`;
const serviceB = `
openapi: 3.0.0
info:
title: Service B
version: 1.0.0
paths:
/users:
get:
tags:
- public
summary: List users B
responses:
'200':
description: OK
/admin:
get:
tags:
- private
summary: Admin endpoint B
responses:
'200':
description: OK
`;
try {
// Create dummy input files and configuration file
fs.writeFileSync(path.join(__dirname, 'service-a.swagger.json'), serviceA);
fs.writeFileSync(path.join(__dirname, 'service-b.swagger.yaml'), serviceB);
fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
console.log('Created openapi-merge.json and dummy input files.');
console.log('Running openapi-merge-cli...');
// Execute the CLI tool using npx
execSync(`npx openapi-merge-cli --config ${configPath}`, { stdio: 'inherit' });
console.log(`OpenAPI specification merged to ${outputPath}`);
console.log('You can now inspect output.swagger.json');
// Optional: Clean up generated files
// fs.unlinkSync(configPath);
// fs.unlinkSync(path.join(__dirname, 'service-a.swagger.json'));
// fs.unlinkSync(path.join(__dirname, 'service-b.swagger.yaml'));
} catch (error) {
console.error('Failed to merge OpenAPI files:', error.message);
process.exit(1);
}
openapi-merge-cli --version
Errors
Common errors & fixes
Error: No configuration file found at 'openapi-merge.json'. Please create one or specify a path with --config.
The `openapi-merge.json` file is missing in the current working directory or the specified path via `--config` is incorrect.
fixCreate an `openapi-merge.json` file in your project root or specify its correct path using `openapi-merge-cli --config ./path/to/my-config.json`.
Input file './missing-service.yaml' not found. Please check the path configured in openapi-merge.json.
An `inputFile` or `inputURL` specified in the `openapi-merge.json` configuration does not point to an existing or accessible file/URL.
fixVerify that all `inputFile` and `inputURL` paths in your `openapi-merge.json` configuration are correct, accessible, and exist.
Error: Component 'MySchema' already exists. Use the 'dispute' option in your configuration to resolve conflicts.
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.
fixAdd a `dispute` object (e.g., `{"prefix": "MyService"}`) to the relevant input entry in `openapi-merge.json` to automatically rename conflicting components. Invalid OpenAPI specification: missing required field 'openapi'
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.
fixValidate 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.
Audit
Dependencies
openapi-mergerequiredProvides the core OpenAPI merging logic and algorithm.