npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@redocly/openapi-core

v1.25.13

Published

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

Downloads

5,241,216

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;