@apidevtools/openapi-schemas

What is @apidevtools/openapi-schemas?

The @apidevtools/openapi-schemas package provides JSON Schema definitions for OpenAPI Specification (OAS) documents. This allows developers to validate their OpenAPI documents against the official OpenAPI schemas, ensuring they adhere to the correct format and standards set by the OpenAPI Initiative.

What are @apidevtools/openapi-schemas's main functionalities?

Validation of OpenAPI documents

This code sample demonstrates how to use the @apidevtools/openapi-schemas package to validate an OpenAPI 3.0 document using the AJV library, which is a popular JSON schema validator.

const Ajv = require('ajv');
const openApiSchema = require('@apidevtools/openapi-schemas');
const ajv = new Ajv();
const validate = ajv.compile(openApiSchema.v3_0);
const openApiDoc = {
  openapi: '3.0.0',
  info: {
    title: 'Sample API',
    version: '1.0'
  },
  paths: {}
};
const valid = validate(openApiDoc);
if (!valid) console.log(validate.errors);

Other packages similar to @apidevtools/openapi-schemas

swagger-parser

Swagger Parser is a package that can parse, validate, and dereference Swagger and OpenAPI documents. Unlike @apidevtools/openapi-schemas, which provides JSON schemas for validation, Swagger Parser offers a more comprehensive solution for handling OpenAPI documents including resolving references and can handle both Swagger 2.0 and OpenAPI 3.0 specifications.

openapi-validator

OpenAPI Validator is another package that validates OpenAPI documents against the OpenAPI Specification. It provides more detailed validation errors and can also validate request and response data in real time, which is not a direct feature of @apidevtools/openapi-schemas. This package is more focused on API runtime validation whereas @apidevtools/openapi-schemas is primarily used for static schema validation.

README

OpenAPI Specification Schemas

This package contains the official JSON Schemas for every version of Swagger/OpenAPI Specification:

Version	Schema	Docs
Swagger 1.2	v1.2 schema	v1.2 docs
Swagger 2.0	v2.0 schema	v2.0 docs
OpenAPI 3.0.x	v3.0.x schema	v3.0.3 docs

All schemas are kept up-to-date with the latest official definitions via an automated CI/CD job. 🤖📦

Installation

You can install OpenAPI Schemas via npm.

npm install @apidevtools/openapi-schemas

Usage

The default export contains all OpenAPI Specification versions:

const openapi = require("@apidevtools/openapi-schemas");

console.log(openapi.v1);    // { $schema, id, properties, definitions, ... }
console.log(openapi.v2);    // { $schema, id, properties, definitions, ... }
console.log(openapi.v3);    // { $schema, id, properties, definitions, ... }

Or you can import the specific version(s) that you need:

const { openapiV1, openapiV2, openapiV3 } = require("@apidevtools/openapi-schemas");

console.log(openapiV1);    // { $schema, id, properties, definitions, ... }
console.log(openapiV2);    // { $schema, id, properties, definitions, ... }
console.log(openapiV3);    // { $schema, id, properties, definitions, ... }

You can use a JSON Schema validator such as Z-Schema or AJV to validate OpenAPI definitions against the specification.

const { openapiV3 } = require("@apidevtools/openapi-schemas");
const ZSchema = require("z-schema");

// Create a ZSchema validator
let validator = new ZSchema();

// Validate an OpenAPI definition against the OpenAPI v3.0 specification
validator.validate(openapiDefinition, openapiV3);

Contributing

Contributions, enhancements, and bug-fixes are welcome! File an issue on GitHub and submit a pull request.

Building

To build the project locally on your computer:

1. Clone this repo
   git clone https://github.com/APIDevTools/openapi-schemas.git

2. Install dependencies
   npm install

3. Build the code
   npm run build

4. Run the tests
   npm test

License

OpenAPI Schemas is 100% free and open-source, under the MIT license. Use it however you want.

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Big Thanks To

Thanks to these awesome companies for their support of Open Source developers ❤