Modern OpenAPI parser written in TypeScript with support for OpenAPI 3.1, OpenAPI 3.0 and Swagger 2.0.
- 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 👀
References are hard and the following features aren’t implemented yet (but will be in the future):
- URLs
npm add @scalar/openapi-parser
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)
}
import { dereference } from '@scalar/openapi-parser'
const specification = `{
"openapi": "3.1.0",
"info": {
"title": "Hello World",
"version": "1.0.0"
},
"paths": {}
}`
const result = await dereference(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'])
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
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()
You can reference other files, too. To do that, the parser needs to know what files are available.
import {
dereference,
fetchUrlsPlugin,
load,
readFilesPlugin,
} from '@scalar/openapi-parser'
// Load a file and all referenced files
const filesystem = await load('./openapi.yaml', {
plugins: [readFilesPlugin(), fetchUrlsPlugin()],
})
// Instead of just passing a single specification, pass the whole “filesystem”
const result = await dereference(filesystem)
As you see, load()
supports plugin. 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 readFilesPlugin
to learn how this could look like.
We are API nerds. You too? Let’s chat on Discord: https://discord.gg/scalar
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.
hanspagel |
marclave |
amritk |
Drew-Kimberly |
x-delfino |
Contributions are welcome! Read CONTRIBUTING
.
The source code in this repository is licensed under MIT.