What is oas-normalize?
The oas-normalize npm package is designed to help developers work with OpenAPI Specification (OAS) documents. It provides functionalities to normalize, validate, and convert OAS documents, making it easier to handle different versions and formats of API specifications.
What are oas-normalize's main functionalities?
Normalization
This feature allows you to normalize an OpenAPI Specification document. The code sample demonstrates how to create an instance of OASNormalize with a path to an OAS file and validate it.
const OASNormalize = require('oas-normalize');
const oas = new OASNormalize('path/to/oas/file');
oas.validate().then(() => {
console.log('OAS is valid');
}).catch(err => {
console.error('OAS is invalid', err);
});
Conversion
This feature allows you to convert an OAS document to a different version or format. The code sample shows how to convert an OAS document and log the converted document.
const OASNormalize = require('oas-normalize');
const oas = new OASNormalize('path/to/oas/file');
oas.convert().then(convertedOAS => {
console.log('Converted OAS:', convertedOAS);
}).catch(err => {
console.error('Conversion failed', err);
});
Dereferencing
This feature allows you to dereference an OAS document, resolving all $ref pointers. The code sample demonstrates how to dereference an OAS document and log the dereferenced document.
const OASNormalize = require('oas-normalize');
const oas = new OASNormalize('path/to/oas/file');
oas.dereference().then(dereferencedOAS => {
console.log('Dereferenced OAS:', dereferencedOAS);
}).catch(err => {
console.error('Dereferencing failed', err);
});
Other packages similar to oas-normalize
swagger-parser
Swagger Parser is a powerful tool for parsing, validating, and dereferencing Swagger and OpenAPI documents. It offers similar functionalities to oas-normalize, such as validation and dereferencing, but also includes additional features like bundling multiple files into a single OAS document.
openapi-schema-validator
OpenAPI Schema Validator is a package focused on validating OpenAPI documents against the OpenAPI Specification. While it does not offer normalization or conversion features, it provides robust validation capabilities, making it a good choice for ensuring OAS compliance.
swagger-client
Swagger Client is a JavaScript client for Swagger and OpenAPI documents. It provides functionalities for parsing, validating, and interacting with OAS documents. Compared to oas-normalize, it offers more features for interacting with APIs defined by OAS documents, such as making HTTP requests.
Swagger 2 or OAS 3? YAML or JSON? URL, path, string or object? Who cares! It just works.
This module uses a bunch of other great modules to do the heavy lifting, and normalizes everything!
Install
npm install oas-normalize --save
Usage
It's pretty simple:
const OASNormalize = require('oas-normalize');
const oas = new OASNormalize('https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml');
oas.validate().then(definition => {
console.log(definition);
}).catch(err => {
console.log(err.errors);
});
Errors
For validation errors, when available, you'll get back an object:
{
"errors": [
{
"message": "User-friendly message",
"path": [...array of the path to the error...]
}
],
"full": ...raw errors...
}
message
is almost always there, but path
is less dependable.
Helper functions
Note: All of these functions are promise-driven.
If you want some more functionality, you can do anything here:
Function | What it does |
---|
.load() | Just load the file, valid or not, as JSON |
.bundle() | Bring together all files into one JSON blob (but retain $ref pointers) |
.deref() | Resolve $ref pointers |
.validate([convertToLatest?])) | Validate the whole thing! |
Other little features
Always return OAS 3
If you want .validate
to always return an OpenAPI 3.0 definition, supply true
as its argument:
OASNormalize.validate(true).then(...);
Enable local paths
For security reasons, you need to enable it; supply enablePaths
to the class instance:
const oas = new OASNormalize('./petstore.json', { enablePaths: true })