Scalar OpenAPI Parser

Modern OpenAPI parser written in TypeScript with support for OpenAPI 3.1, OpenAPI 3.0 and Swagger 2.0.

Goals

Written in TypeScript
Runs in Node.js and in the browser (without any polyfills or configuration)
Tested with hundreds of real world examples
Amazing error output
Support for OpenAPI 4.0 👀

Limitations

References are hard and the following features aren’t implemented yet (but will be in the future):

URLs

Installation

npm add @scalar/openapi-parser

Usage

Validate

import { validate } from '@scalar/openapi-parser'

const file = `{
  "openapi": "3.1.0",
  "info": {
    "title": "Hello World",
    "version": "1.0.0"
  },
  "paths": {}
}`

const result = await validate(file)

console.log(result.valid)

if (!result.valid) {
  console.log(result.errors)
}

Resolve references

import { resolve } from '@scalar/openapi-parser'

const specification = `{
  "openapi": "3.1.0",
  "info": {
    "title": "Hello World",
    "version": "1.0.0"
  },
  "paths": {}
}`

const result = await resolve(specification)

Modify an OpenAPI specification

import { filter } from '@scalar/openapi-parser'

const specification = `{
  "openapi": "3.1.0",
  "info": {
    "title": "Hello World",
    "version": "1.0.0"
  },
  "paths": {}
}`

const result = filter(specification, (schema) => !schema?.['x-internal'])

Upgrade your OpenAPI specification

There’s an upgrade command to upgrade all your OpenAPI specifications to the latest OpenAPI version.

⚠️ Currently, only an upgrade from OpenAPI 3.0 to OpenAPI 3.1 is supported. Swagger 2.0 is not supported (yet).

import { upgrade } from '@scalar/openapi-parser'

const result = upgrade({
  openapi: '3.0.0',
  info: {
    title: 'Hello World',
    version: '1.0.0',
  },
  paths: {},
})

console.log(result.openapi)
// Output: 3.1.0

Pipeline syntax

import { openapi } from '@scalar/openapi-parser'

const specification = …

// New pipeline …
const result = openapi()
  // loads the specification …
  .load(specification)
  // upgrades to OpenAPI 3.1 …
  .upgrade()
  // removes all internal operations …
  .filter((schema) => !schema?.['x-internal'])
  // done!
  .get()

Advanced: File references

You can reference other files, too. To do that, the parser needs to know what files are available.

import { loadFiles } from '@scalar/openapi-parser'

// load a file and all referenced files
const filesystem = loadFiles('./openapi.yaml')
// instead of just passing a single specification, pass the whole “filesystem”
const result = await resolve(filesystem)

You don’t have to use loadFiles, though. You just need to stick to the format. That enables you store the files wherever you want (maybe in a database?) or to use the package in a browser environment.

Community

We are API nerds. You too? Let’s chat on Discord: https://discord.gg/scalar

Thank you!

Thanks a ton for all the help and inspiration:

@philsturgeon to make sure we build something we won’t hate.
We took a lot of inspiration from @seriousme and his package openapi-schema-validator early-on.
You could consider this package the modern successor of @apidevtools/swagger-parser, we even test against it to make sure we’re getting the same results (where intended).
We stole a lot of example specification from @mermade to test against.