chore: new package api

[hanspagel]

This PR is huge:

• major refactor
• support for multiple files
• a ton more tests
• a new package API

It’s not really done, but let’s get this out and take some smaller steps to iterate on it. :)

Validate

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

const result = await openapi().load(specification).validate()

expect(result).toMatchObject({
  valid: true,
  version: '3.1',
})

Filter

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

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

Resolve

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

const result = await openapi().load(specification).resolve()

Upgrade to OpenAPI 3.1

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

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

The package also exposes a ton of utilities which you can use like building blocks:

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

// pass an object, JSON or YAML and get an object
const result = normalize(input)

Modify the given specification

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

// recursively go through the specification and modify it on all levels
const result = traverse(specification, (schema) => {
  schema['x-annotation'] = 'foobar'

  return schema
})