Security News
Python Overtakes JavaScript as Top Programming Language on GitHub
Python becomes GitHub's top language in 2024, driven by AI and data science projects, while AI-powered security tools are gaining adoption.
@redocly/openapi-core
Advanced tools
@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.
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);
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 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 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.
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.
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 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 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 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 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,
});
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;
FAQs
See https://github.com/Redocly/redocly-cli
We found that @redocly/openapi-core demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 9 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Python becomes GitHub's top language in 2024, driven by AI and data science projects, while AI-powered security tools are gaining adoption.
Security News
Dutch National Police and FBI dismantle Redline and Meta infostealer malware-as-a-service operations in Operation Magnus, seizing servers and source code.
Research
Security News
Socket is tracking a new trend where malicious actors are now exploiting the popularity of LLM research to spread malware through seemingly useful open source packages.