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;