Skip to content
This repository has been archived by the owner on Aug 28, 2024. It is now read-only.

Latest commit

 

History

History
303 lines (236 loc) · 8.44 KB

README.md

File metadata and controls

303 lines (236 loc) · 8.44 KB

Warning

We moved @scalar/openapi-parser to https://github.com/scalar/scalar

Scalar OpenAPI Parser

CI Contributors GitHub License Discord

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 👀

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 { valid, errors } = await validate(file)

console.log(valid)

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

Resolve references

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

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

const { schema, errors } = await dereference(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 { specification } = 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 { specification } = upgrade({
  openapi: '3.0.0',
  info: {
    title: 'Hello World',
    version: '1.0.0',
  },
  paths: {},
})

console.log(specification.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()

Then/Catch syntax

If you’re more the then/catch type of guy, that’s fine:

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

const specification = 

validate(specification, {
  throwOnError: true,
})
.then(result => {
  // Success
})
.catch(error => {
  // Failure
})

TypeScript

If you just look for our types, you can install the package separately:

npm add @scalar/openapi-types

And use it like this:

import type { OpenAPI } from '@scalar/openapi-types'

const file: OpenAPI.Document = {
  openapi: '3.1.0',
  info: {
    title: 'Hello World',
    version: '1.0.0',
  },
  paths: {},
}

Advanced: URL and file references

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

import { dereference, load } from '@scalar/openapi-parser'
import { fetchUrls } from '@scalar/openapi-parser/plugins/fetch-urls'
import { readFiles } from '@scalar/openapi-parser/plugins/read-files'

// Load a file and all referenced files
const { filesystem } = await load('./openapi.yaml', {
  plugins: [
    readFiles(),
    fetchUrls({
      limit: 5,
    }),
  ],
})

// Instead of just passing a single specification, pass the whole “filesystem”
const result = await dereference(filesystem)

As you see, load() supports plugins. You can write your own plugin, if you’d like to fetch API defintions from another data source, for example your database. Look at the source code of the readFiles to learn how this could look like.

Directly load URLs

Once the fetchUrls plugin is loaded, you can also just pass an URL:

import { dereference, load } from '@scalar/openapi-parser'
import { fetchUrls } from '@scalar/openapi-parser/plugins/fetch-urls'

// Load a file and all referenced files
const { filesystem } = await load(
  'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml',
  {
    plugins: [fetchUrls()],
  },
)

Intercept HTTP requests

If you’re using the package in a browser environment, you may run into CORS issues when fetching from URLs. You can intercept the requests, for example to use a proxy, though:

import { dereference, load } from '@scalar/openapi-parser'
import { fetchUrls } from '@scalar/openapi-parser/plugins/fetch-urls'

// Load a file and all referenced files
const { filesystem } = await load(
  'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml',
  {
    plugins: [
      fetchUrls({
        fetch: (url) => fetch(url.replace('BANANA.net', 'jsdelivr.net')),
      }).get('https://cdn.BANANA.net/npm/@scalar/galaxy/dist/latest.yaml'),
    ],
  },
)

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:

Contributors

hanspagel
hanspagel
marclave
marclave
amritk
amritk
Drew-Kimberly
Drew-Kimberly
tmcw
tmcw
x-delfino
x-delfino

Contributions are welcome! Read CONTRIBUTING.

License

The source code in this repository is licensed under MIT.