openapi-transformer-base

Base class for traversing or transforming OpenAPI 2 or 3 documents using a modified visitor design pattern to traverse object types within the OpenAPI document tree.

Usage no npm install needed!

<script type="module">
  import openapiTransformerBase from 'https://cdn.skypack.dev/openapi-transformer-base';
</script>

README

OpenApiTransformerBase

Build Status Coverage Dependency Status Supported Node Version Version on NPM

Base class for traversing or transforming OpenAPI 2 or OpenAPI 3 documents using a modified visitor design pattern to traverse object types within the OpenAPI document tree.

This class is used to implement several common OpenAPI document transformations in @kevinoid/openapi-transformers.

Introductory Examples

Gather External Documentation

To gather all External Documentation objects in an OpenAPI 3 document using an ad-hoc (i.e. monkey-patched) subclass:

const OpenApiTransformerBase = require('openapi-transformer-base');
const { readFile } = require('fs').promises;

readFile('openapi.json', 'utf8')
  .then((openApiString) => {
    // Array which holds the collected externalDocs
    const allExternalDocs = [];

    // Create ad-hoc subclass of OpenApiTransformerBase to collect externalDocs
    const transformer = new OpenApiTransformerBase();
    transformer.transformExternalDocs = (externalDocs) => {
      allExternalDocs.push(externalDocs);
      return externalDocs;
    };

    // Parse, then traverse the OpenAPI document
    const openApi = JSON.parse(openApiString);
    transformer.transformOpenApi(openApi);

    console.log('All External Documentation:', allExternalDocs);
  });

Change Integer to Number Schema Type

Since type: integer is an OpenAPI-specific extension of type in JSON Schema, it may be desirable to change schemas with type: integer to type: number with multipleOf: 1 for use by JSON Schema tools:

const OpenApiTransformerBase = require('openapi-transformer-base');
const { readFile } = require('fs').promises;

class OpenApiIntegerTypeTransformer extends OpenApiTransformerBase {
  transformSchema(schema) {
    // Perform any other transformations on this schema or its child objects
    let newSchema = super.transformSchema(schema);

    if (newSchema.type === 'integer') {
      newSchema = {
        ...newSchema,
        type: 'number',
        multipleOf: 1,
      };
    }

    return newSchema;
  }
}

readFile('openapi.json', 'utf8')
  .then((openApiString) => {
    const openApi = JSON.parse(openApiString);

    const transformer = new OpenApiIntegerTypeTransformer();
    const newOpenApi = transformer.transformOpenApi(openApi);
    console.log('Transformed OpenAPI Document:', newOpenApi);
  });

More examples can be found in the test specifications.

API Docs

See the JSDoc API Documentation.

Contributing

Contributions are appreciated. Contributors agree to abide by the Contributor Covenant Code of Conduct. If this is your first time contributing to a Free and Open Source Software project, consider reading How to Contribute to Open Source in the Open Source Guides.

If the desired change is large, complex, backwards-incompatible, can have significantly differing implementations, or may not be in scope for this project, opening an issue before writing the code can avoid frustration and save a lot of time and effort.

License

This project is available under the terms of the MIT License. See the summary at TLDRLegal.