@redocly/openapi-core

What is @redocly/openapi-core?

@redocly/openapi-core is a powerful tool for working with OpenAPI definitions. It provides functionalities for validating, bundling, and transforming OpenAPI documents, making it easier to manage and maintain API specifications.

What are @redocly/openapi-core's main functionalities?

Validation

This feature allows you to validate an OpenAPI document to ensure it adheres to the OpenAPI specification. The code sample demonstrates how to use the `validate` function to check an OpenAPI document.

const { validate } = require('@redocly/openapi-core');

async function validateOpenAPIDocument(document) {
  const result = await validate({ definition: document });
  console.log(result);
}

const openAPIDocument = { /* your OpenAPI document here */ };
validateOpenAPIDocument(openAPIDocument);

Bundling

This feature allows you to bundle multiple OpenAPI files into a single document. The code sample demonstrates how to use the `bundle` function to combine an OpenAPI document.

const { bundle } = require('@redocly/openapi-core');

async function bundleOpenAPIDocument(document) {
  const result = await bundle({ definition: document });
  console.log(result);
}

const openAPIDocument = { /* your OpenAPI document here */ };
bundleOpenAPIDocument(openAPIDocument);

Transforming

This feature allows you to transform an OpenAPI document based on specific options. The code sample demonstrates how to use the `transform` function to modify an OpenAPI document.

const { transform } = require('@redocly/openapi-core');

async function transformOpenAPIDocument(document, options) {
  const result = await transform({ definition: document, ...options });
  console.log(result);
}

const openAPIDocument = { /* your OpenAPI document here */ };
const transformOptions = { /* your transformation options here */ };
transformOpenAPIDocument(openAPIDocument, transformOptions);

Other packages similar to @redocly/openapi-core

swagger-parser

swagger-parser is a powerful tool for parsing, validating, and dereferencing Swagger and OpenAPI documents. It provides similar functionalities to @redocly/openapi-core, such as validation and dereferencing, but it does not offer as extensive transformation capabilities.

openapi-validator

openapi-validator is a package focused on validating OpenAPI documents. It provides comprehensive validation features but lacks the bundling and transformation functionalities offered by @redocly/openapi-core.

swagger-jsdoc

swagger-jsdoc is a tool for generating Swagger (OpenAPI) definitions from JSDoc comments in your code. While it focuses on generating OpenAPI documents rather than validating or transforming them, it can be used in conjunction with @redocly/openapi-core for a complete workflow.

README

openapi-core

See https://github.com/Redocly/redocly-cli

[!IMPORTANT] The openapi-core package is designed for our internal use; the interfaces that are considered safe to use are documented below. Some of the function arguments are not documented below because they are not intended for public use. Avoid using any functions or features that are not documented below. If your use case is not documented below, please open an issue.

Basic usage

Lint from file system

Lint a file, optionally with a config file.

import { lint, loadConfig } from '@redocly/openapi-core';

const pathToApi = 'openapi.yaml';
const config = await loadConfig({ configPath: 'optional/path/to/redocly.yaml' });
const lintResults = await lint({ ref: pathToApi, config });

The content of lintResults describes any errors or warnings found during linting; an empty array means no problems were found. For each problem, the rule, severity, feedback message and a location object are provided. To learn more, check the lint function section.

Bundle from file system

Bundle an API description into a single structure, optionally with a config file.

import { bundle, loadConfig } from '@redocly/openapi-core';

const pathToApi = 'openapi.yaml';
const config = await loadConfig({ configPath: 'optional/path/to/redocly.yaml' });
const bundleResults = await bundle({ ref: pathToApi, config });

In bundleResults, the bundle.parsed field has the bundled API description. For more information, check the bundle function section.

Lint from memory with config

Lint an API description, with configuration defined. This is useful if the API description you're working with isn't a file on disk.

import { lintFromString, createConfig, stringifyYaml } from '@redocly/openapi-core';

const config = await createConfig(
  {
    extends: ['minimal'],
    rules: {
      'operation-description': 'error',
    },
  },
  {
    // optionally provide config path for resolving $refs and proper error locations
    configPath: 'optional/path/to/redocly.yaml',
  }
);
const source = stringifyYaml({ openapi: '3.0.1' /* ... */ }); // you can also use JSON.stringify
const lintResults = await lintFromString({
  source,
  // optionally pass path to the file for resolving $refs and proper error locations
  absoluteRef: 'optional/path/to/openapi.yaml',
  config,
});

Lint from memory with a custom plugin

Lint an API description, with configuration including a custom plugin to define a rule.

import { lintFromString, createConfig, stringifyYaml } from '@redocly/openapi-core';

const CustomRule = (ruleOptions) => {
  return {
    Operation() {
      // some rule logic
    },
  };
};

const config = await createConfig({
  extends: ['recommended'],
  plugins: [
    {
      id: 'pluginId',
      rules: {
        oas3: {
          customRule1: CustomRule,
        },
        oas2: {
          customRule1: CustomRule, // if the same rule can handle both oas3 and oas2
        },
      },
      decorators: {
        // ...
      },
    },
  ],
  // enable rule
  rules: {
    'pluginId/customRule1': 'error',
  },
  decorators: {
    // ...
  },
});

const source = stringifyYaml({ openapi: '3.0.1' /* ... */ }); // you can also use JSON.stringify
const lintResults = await lintFromString({
  source,
  // optionally pass path to the file for resolving $refs and proper error locations
  absoluteRef: 'optional/path/to/openapi.yaml',
  config,
});

Bundle from memory

Bundle an API description into a single structure, using default configuration.

import { bundleFromString, createConfig } from '@redocly/openapi-core';

const config = await createConfig({}); // create empty config
const source = stringifyYaml({ openapi: '3.0.1' /* ... */ }); // you can also use JSON.stringify
const bundleResults = await bundleFromString({
  source,
  // optionally pass path to the file for resolving $refs and proper error locations
  absoluteRef: 'optional/path/to/openapi.yaml',
  config,
});

API

createConfig

Creates a config object from a JSON or YAML string or JS object. Resolves remote config from extends (if there are URLs or local fs paths).

async function createConfig(
  // JSON or YAML string or object with Redocly config
  config: string | RawUniversalConfig,
  options?: {
    // optional path to the config file for resolving $refs and proper error locations
    configPath?: string;
  }
): Promise<Config>;

loadConfig

Loads a config object from a file system. If configPath is not provided, it tries to find redocly.yaml in the current working directory.

async function loadConfig(options?: {
  // optional path to the config file for resolving $refs and proper error locations
  configPath?: string;
  // allows to add custom `extends` additionally to one from the config file
  customExtends?: string[];
}): Promise<Config>;

lint

Lint an OpenAPI document from the file system.

async function lint(options: {
  // path to the OpenAPI document root
  ref: string;
  // config object
  config: Config;
}): Promise<NormalizedProblem[]>;

lintFromString

Lint an OpenAPI document from a string.

async function lintFromString(options: {
  // OpenAPI document string
  source: string;
  // optional path to the OpenAPI document for resolving $refs and proper error locations
  absoluteRef?: string;
  // config object
  config: Config;
}): Promise<NormalizedProblem[]>;

bundle

Bundle an OpenAPI document from the file system.

async function bundle(options: {
  // path to the OpenAPI document root
  ref: string;
  // config object
  config: Config;
  // whether to fully dereference $refs, resulting document won't have any $ref
  // warning: this can produce circular objects
  dereference?: boolean;
  // whether to remove unused components (schemas, parameters, responses, etc)
  removeUnusedComponents?: boolean;
  // whether to keep $ref pointers to the http URLs and resolve only local fs $refs
  keepUrlRefs?: boolean;
}): Promise<{
    bundle: {
      parsed: object; // OpenAPI document object as js object
    };
    problems: NormalizedProblem[]
    fileDependencies
    rootType
    refTypes
    visitorsData

  }>;

bundleFromString

Bundle an OpenAPI document from a string.

async function bundleFromString(options: {
  // OpenAPI document string
  source: string;
  // optional path to the OpenAPI document for resolving $refs and proper error locations
  absoluteRef?: string;
  // config object
  config: Config;
  // whether to fully dereference $refs, resulting document won't have any $ref
  // warning: this can produce circular objects
  dereference?: boolean;
  // whether to remove unused components (schemas, parameters, responses, etc)
  removeUnusedComponents?: boolean;
  // whether to keep $ref pointers to the http URLs and resolve only local fs $refs
  keepUrlRefs?: boolean;
}): Promise<{
    bundle: {
      parsed: object; // OpenAPI document object as js object
    };
    problems: NormalizedProblem[]
    fileDependencies
    rootType
    refTypes
    visitorsData

  }>;

stringifyYaml

Helper function to stringify a javascript object to YAML.

function stringifyYaml(obj: object): string;