scalar / openapi-parser

Modern OpenAPI parser written in TypeScript

Scalar OpenAPI Parser

⚠️ This package is in early development. Don’t use it in production (yet).

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):

• references inside inside referenced files (recursion, yay)
• circular references in referenced files (recursion inside recursion, yay)
• URLs (low priority though)

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 file = `{
  "openapi": "3.1.0",
  "info": {
    "title": "Hello World",
    "version": "1.0.0"
  },
  "paths": {}
}`

const result = await resolve(file)

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).

const specification = openapi()
  .load({
    openapi: '3.0.0',
    info: {
      title: 'Hello World',
      version: '1.0.0',
    },
    paths: {},
  })
  .upgrade()
  .get()

Community

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

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]https://github.com/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

Contributions are welcome! Read CONTRIBUTING.

License

The source code in this repository is licensed under MIT.