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.

Contributors

hanspagel

marclave

amritk

Drew-Kimberly

Contributions are welcome! Read CONTRIBUTING.

License

The source code in this repository is licensed under MIT.