openapi-merge

What is openapi-merge?

The openapi-merge npm package is designed to merge multiple OpenAPI (Swagger) specification files into a single file. This can be particularly useful for large projects where APIs are defined in separate files for modularity and need to be combined for documentation or other purposes.

What are openapi-merge's main functionalities?

Merge Multiple OpenAPI Files

This feature allows you to merge multiple OpenAPI specification files into a single file. The code sample demonstrates how to read two OpenAPI files, merge them using the openapi-merge package, and then write the merged result to a new file.

const { merge } = require('openapi-merge');
const fs = require('fs');

const file1 = JSON.parse(fs.readFileSync('path/to/openapi1.json', 'utf8'));
const file2 = JSON.parse(fs.readFileSync('path/to/openapi2.json', 'utf8'));

const merged = merge([file1, file2]);

fs.writeFileSync('path/to/merged-openapi.json', JSON.stringify(merged, null, 2));

Custom Merge Options

This feature allows you to specify custom options for the merge process. The code sample shows how to use an options object to customize the merging behavior, such as ignoring conflicts.

const { merge } = require('openapi-merge');
const fs = require('fs');

const file1 = JSON.parse(fs.readFileSync('path/to/openapi1.json', 'utf8'));
const file2 = JSON.parse(fs.readFileSync('path/to/openapi2.json', 'utf8'));

const options = {
  // Custom options for merging
  ignoreConflicts: true
};

const merged = merge([file1, file2], options);

fs.writeFileSync('path/to/merged-openapi.json', JSON.stringify(merged, null, 2));

Other packages similar to openapi-merge

swagger-combine

The swagger-combine package allows you to combine multiple Swagger (OpenAPI) files into one. It offers more configuration options and supports YAML format, which can be more readable for large API definitions. Compared to openapi-merge, swagger-combine provides more flexibility in terms of configuration but may require more setup.

swagger-parser

The swagger-parser package is primarily used for parsing, validating, and dereferencing Swagger (OpenAPI) files. While it doesn't directly merge files, it can be used in conjunction with other tools to achieve similar results. It offers robust validation features that can complement the merging process.

openapi-diff

The openapi-diff package is used to compare two OpenAPI specifications and highlight the differences. While it doesn't merge files, it can be useful for identifying changes between versions of API specifications, which can be a helpful step before merging. It provides detailed reports on what has changed between two OpenAPI files.

README

openapi-merge

This library assumes that you have a number of microservices that you wish to expose through one main service or gateway.

With this assumption in mind, it allows you to provide multiple OpenAPI 3.0 files and have them be merged together, in a deterministic manner, into a single OpenAPI specification.

Many of the design decisions of this library have that use case in mind and thus the features will be geared to making that be a good experience.

If you are looking for a CLI tool based on this library, then please check out:

How to use this library

This library is intended to be used in a JavaScript or Typescript project. Here is a Typescript example that will work 100%:

import { merge, isErrorResult } from 'openapi-merge';
import { Swagger } from 'atlassian-openapi';

// Does not have to use the 'SwaggerV3' type, the merge function will accept 'any' so long as the underlying object is valid
const oas1: Swagger.SwaggerV3 = {
  openapi: "3.0.2",
  info: {
    title: "First Input",
    description: "Merge conflicts often use the first element",
    version: "1.0"
  },
  paths: {
    "/cats": {
      get: {
        summary: 'Get the cats',
        responses: {
          200: {
            description: "All of the cats"
          }
        }
      }
    }
  }
};

const oas2: Swagger.SwaggerV3 = {
  openapi: "3.0.2",
  info: {
    title: "Second Input",
    version: "1.0"
  },
  paths: {
    "/dogs": {
      get: {
        summary: 'Get the dogs',
        responses: {
          200: {
            description: "All of the dogs"
          }
        }
      }
    }
  }
};

function main() {
  const mergeResult = merge([{
    oas: oas1,
    pathModification: {
      prepend: '/one'
    }
  }, {
    oas: oas2,
    pathModification: {
      prepend: '/two'
    }
  }]);

  if (isErrorResult(mergeResult)) {
    // Oops, something went wrong
    console.error(`${mergeResult.message} (${mergeResult.type})`);
  } else {
    console.log(`Merge successful!`);
    console.log(JSON.stringify(mergeResult.output, null, 2));
  }
}

main();

If you wish to play around with this example further, then please fork this Repl.

Merging Behaviour

We process the inputs sequentially such that the first input in the list takes preference and subsequent inputs will be modified to merge seamlessly into the first.

For some parts of the OpenAPI file, like paths, components and tags we attempt to merge the definitions together such that there are no overlaps and no information is dropped.

However, for other elements of the OpenAPI files, the algorithm simply takes the value that is first defined in the list of OpenAPI files. Examples of elements of the OpenAPI files that follow this pattern are:

• Info
• Servers
• Security Schemes
• ExternalDocumentation

The intention here is that the first file will define these elements and effectively override them from the other files. This matches the "API gateway" use case that we have mentioned previously whereby we probably want these definitions to be specific to the API gateway and thus override the top level definitions from other inputs.