Aggregate multiple swagger specs into a single file. Useful when providing a combined definition for multiple microservices

swagger, aggregate, typescript, microservices, aggregation
npm install @swimlane/swinger@1.0.0



Build Status Codacy Badge Codacy Badge

Swagger aggregation for microservices!

Swinger merges multiple swagger specifications into a single file. This allows you to provide a single specification that covers all your microservices.


  • Merges any number of specifications
  • Applies basePath (swagger 2.0) and security globals to every path before merging
  • Namespaces definitions (swagger 2.0) if there are collisions
  • Updates references ($ref) to include proper namespace
  • Merges and deduplicates tags
  • Merges securityDefinitions (swagger 2.0), deduplicating when named entry is shared between specs
  • No external dependencies
  • Typescript typings included


npm install @swimlane/swinger


Swinger provides a merge() function. This function takes an array of Swagger specs in object (JSON) format. It then merges left to right. The first spec in the array is treated as the Final spec with all the others merged into it.


import * as swinger from 'swinger';

// get your specs from somewhere
const specs = getSpecs();

const masterSpec = {
  info: {
    title: 'Merged Spec',
    description: 'One spec to rule them all'
  basePath: '/api',
  tags: [ 'merged' ]

const mergedSpec = swinger.merge([masterSpec, ...specs]);


swinger is a Swimlane open-source project; we believe in giving back to the open-source community by sharing some of the projects we build for our application. Swimlane is a security automation and orchestration (SAO) platform. Our platform empowers organizations to manage, respond to and neutralize cyber threats with the adaptability, efficiency and speed necessary to combat today’s rapidly evolving cyber threats.