README

Mateo API Description Library

This project aims to provide a user-friendly interface to various API description formats, like Open API (Swagger) and API Blueprint, to efficiently build cross-format tools using common sense components. The overwhelming majority of use cases involve reading an API description and taking some (read-only) action:

Generating documentation
Generating server or client code
Running a mock server
Running automated tests
Checking for errors / validation

To support these use cases while remaining simple, this library is read-only and cannot be used to edit an API description. This means it is purely a library to consume API description formats and cannot be used to convert between formats. The goals of this library are:

Be useful to developers
Be straightforward to use
Be convenient whenever possible
Be built on existing popular standards whenever possible
Be built with real world use cases in mind

Currently supported API formats:

Swagger 2.0
API Blueprint with support for Hercule transclusion

Due to the nature of various API description formats supporting different features, this library will attempt to massage various pieces to fit into common sense components without losing too much in translation. If you need 100% 1:1 accuracy, you may be better off parsing the format of your choice manually.

Note: This library is built using modern Javascript functionality without a transpiler, and thus requires either a recent Node.js version (6.0+) or to be run through a transpiler (e.g. Webpack + Babel for usage in a browser) before being used.

Library Usage

The Mateo API description library can be installed via npm:

npm install --save mateo

Once installed, you can easily parse any supported API format:

import Mateo from 'mateo';

// Usage via callbacks
Mateo.parse('...', (err, api) => {
  if (err) {
    console.log(err);
    return;
  }

  console.log(api);
});

// Usage via promises
Mateo.parse('...').then((api) => {
  console.log(api);
}).catch((err) => {
  console.log(err);
})

Library Documentation

`Mateo`

`Mateo.parse(apiDescription, [options], [done])`

Parse an API description from a string. The api is an Api instance. If no callback done function is given, then the promise-based interface is used and a promise is returned.

const options = {
  filename: 'foo.yaml'
};

Mateo.parse('...', options, (err, api) => { /* ... */ });

`Mateo.parseFile(filename, [done])`

Parse an API description from a file. The api is an Api instance.

Mateo.parseFile('.../file.yaml', (err, api) => { /* ... */ });

TODO

License

https://dgt.mit-license.org/

Usage no npm install needed!