authress-engineering / openapi-resolver.js

Javascript library to connect to parse and resolve openapi-enabled APIs via browser or nodejs

OpenAPI Resolver

OpenAPI Resolver is a JavaScript module that allows you to fetch, resolve, and interact with Swagger/OpenAPI documents.

New!

This is the new version of swagger-js, 3.x. The OpenAPI Resolver replaces swagger-js.

Compatibility

The OpenAPI Specification has undergone multiple revisions since initial creation in 2010. Compatibility between OpenAPI Resolver and the OpenAPI Specification is as follows:

OpenAPI Resolver Version	Release Date	OpenAPI Spec compatibility	Notes
3.10.x	2020-01-17	2.0, 3.0.0
4.x	2022-07-24	2.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.1.0

Installation

We publish single module to npm: openapi-resolver. openapi-resolver is meant for consumption by any JavaScript engine (node.js, browser, etc...). The npm package contains transpiled and minified ES5 compatible code.

 $ npm install openapi-resolver

After installed successfully:

ES6 imports

import openApiResolver from 'openapi-resolver';

CommonJS imports

const openApiResolver = require('openapi-resolver');

Usage

import openApiResolver from 'openapi-resolver';

const spec = await openApiResolver('http://petstore.swagger.io/v2/swagger.json');

Runtime

• Node.js: lts
• openapi-resolver works in the latest versions of Chrome, Safari, Firefox, and Edge.

Security contact

Please disclose any security-related issues or vulnerabilities by emailing [email protected], instead of using the public issue tracker.

openapi-resolver.js's Issues

If example contains `null` the whole resolver breaks and errors out as there is no null check in `handleCircularReferences`

Q&A (please complete the following information)

• OS: [e.g. macOS] Windows
• Environment: [e.g. Chrome 59, Node.js v10.0.0] Firefox 104
• Method of installation: [e.g. npm, unpkg] npm
• OpenAPI Resolver version: [e.g. 3.8.0] latest
• OpenAPI version: [e.g. Swagger 2.0, OpenAPI 3.0, OpenAPI 3.1] OpenAPI 3.0

Content & configuration

OpenAPI definition:

# Can't share

OpenAPI Resolver usage:

openApiResolver({
  // Not used
})

Describe the bug you're encountering

To reproduce...

Steps to reproduce the behavior:

1. Have an example in your OpenAPI docs which contains a null value, in our case it's for the deleted_at column
2. Try loading it with OpenAPI Explorer, debug the whole day, figure out it's inside this package and find the root cause

Expected behavior

It should just parse

Screenshots

Additional context or thoughts

The error is caused on the following line:
https://github.com/Rhosys/openapi-resolver.js/blob/f16c6e828948f3af44b7956dee7c48bbc5b2202b/src/index.js#L15

For some reason its also parsing the example object, which in our case contains a deleted_at: null - this results in the above line to error out as there is a null being passed in and because Javascript is weird: typeof null === "object"

Allow broken specs to still resolve as much as possible

Content & configuration

OpenAPI definition:

{
 "openapi": "3.0.1",
 "info": {
   "title": "Swagger Petstore",
   "description": "This is a sample server Petstore server.  You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).  For this sample, you can use the api key `special-key` to test the authorization filters.",
   "termsOfService": "http://swagger.io/terms/",
   "contact": {
     "email": "[email protected]"
   },
   "license": {
     "name": "Apache 2.0",
     "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
   },
   "version": "1.0.6"
 },
 "servers": [
   {
     "url": "http://localhost:8088"
   }
 ],
 "paths": {
   "/pet": {
     "post": {
       "summary": "",
       "description": "",
       "tags": [
         "pet"
       ],
       "operationId": "createPet",
       "requestBody": {
         "description": "Pet to create",
         "content": {
           "application/json": {
             "schema": {
               "$ref": "#/components/schemas/Pet"
             }
           }
         }
       }
     }
   }
 },
 "tags": [
   {
     "name": "pet",
     "description": "Everything about your Pets",
     "externalDocs": {
       "description": "Find out more",
       "url": "http://swagger.io"
     }
   }
 ],
 "components": {
   "schemas": {
   }
 }
}

OpenAPI Resolver usage:

const openApiResolver = require('openapi-resolver');
...
const resolved = await openApiResolver(obj);

Is your feature request related to a problem?

There currently is not a way to "continueOnError" like there is in the json-schema-ref-parser library. This can have some benefits in situations where the goal is to resolve JSON Schema references with a best effort. For example, here is the code that I use to place the "any" JSON Schema in place of a missing JSON Schema reference (pointer is the "json-pointer" module):

/**
 * Utilizes the openapi-resolver library to handle dereferencing as much as possible.  For references that use an
 * invalid or missing pointer, the "any" schema will be placed where the dereferenced JSON Schema would go.
 * @param {object} obj - The object to dereference
 * @returns {object} - Dereferenced object to the best of the ability of the library and error handling
 */
const dereference = async (obj) => {
  try {
    const resolved = await openApiResolver(obj);

    return resolved;
  } catch (err) {
    const {
      errors = [],
    } = err;

    const allowedErrors = errors.filter((error) => ['MissingPointerError', 'InvalidPointerError'].includes(error.name));

    if (allowedErrors.length !== errors.length) throw err;

    const parsed = err.files.schema;
    allowedErrors.forEach((error) => {
      pointer.set(parsed, pointer.compile(error.path), { type: ['array', 'boolean', 'number', 'object', 'string'] });
    });

    return parsed;
  }
};

Describe the solution you'd like

Some options be added to the library. One would be an option that would be passed into the options object of json-schema-ref-parser as the "continueOnError" option. I understand that you are forcing the dereference.circular option to be "ignore", so I'm not asking for the full compliment of options be made available, but some of the options are helpful. In this case, at least one option that maps to the "continueOnError" option is requested.

path tags should always be an array

Operations can have tags, tags can either be a string or an array according to the spec. But when loaded this should always be converted to an array to make it easy to deal with.