Skip to content
This repository has been archived by the owner on Jul 3, 2023. It is now read-only.

Node library used to recursively searches a directory for a regex or pattern to find OpenAPI (fka Swagger) specs; subsequently validates, bundles and merges them into one spec. Optionally writes merged spec to a file.

Notifications You must be signed in to change notification settings

Typeform/openapi-micro-merge

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

28 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

IMPORTANT NOTE

⚠️ This library hasn't been maintained for a while so we've decided to deprecate it and archive the repository. Feel free to fork it!


openapi-micro-merge

Build Status

Node library used to recursively search a directory for a regex or pattern to find OpenAPI specs; subsequently validates, bundles and merges them into one spec. Optionally writes merged spec to a file.

This is very useful for microservice environments where service specs are stored in separate directories, but need to be merged into one file for various purposes (docs, tooling, etc). Intended to be used in CI environments, where validating specs is a critical need.

Features

  • OpenAPI (fka Swagger) 2.0
  • Recursive regex or pattern search for specs in directories
  • Callbacks or Promises (fast with Bluebird)
  • YAML or JSON specs supported
    • Info file must be in YAML
  • Validation of each spec
  • $ref support, linked specs/schema/parameters
  • Sorts tags by name

Install

  npm install openapi-micro-merge

Usage

  var microMerge = require('openapi-micro-merge');

  const specDir = './specs/'; // Directory to recursively search
  const specFile = 'openapi.json'; //  a regex pattern or array to find OpenAPI specs
  const infoFile = './test/info.yaml';
  const host = 'api.test.com';
  const schemes = ['http', 'https'];
  const basePath = '/';
  const options = {visibilityFilter: 'EXTERNAL', statusFilter: 'RELEASED'};
  const outputFile = './test/swagger.json'

  // Returns a merged OpenAPI object
  microMerge.prepare(specDir, specFile, infoFile, host, schemes, basePath, options,
    function(err, data) {
      console.log(data);
  });

  // Returns a merged OpenAPI object in a Promise
  microMerge.preparePromise(specDir, host, specFile, basePath, infoFile, schemes)
    .then((apis) => {
      console.log(apis);
    });

  // Writes a merged OpenAPI spec
  microMerge.write(specDir, specFile, infoFile, host, schemes, basePath, options, outputFile, 
    function(err) {
      if (err) {
        console.log(err);
       }
  });

Extensions

OpenAPI extensions are supported to aid in filtering the list of operations based on the audience.

  • x-visibility:
    • path level: Determines if path is for external or internal use.
    • Allowed options: EXTERNAL, INTERNAL.
  • x-status:
    • path level: Determines development status of the path.
    • Allowed options: PROPOSED, IN_DEVELOPMENT, RELEASED

TODO

  • Strip all extensions
  • YAML output for merged spec in save()
  • Full dereferencing option instead of bundling
  • Support JSON for info file
  • Tag sorting optional

About

Node library used to recursively searches a directory for a regex or pattern to find OpenAPI (fka Swagger) specs; subsequently validates, bundles and merges them into one spec. Optionally writes merged spec to a file.

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published