feat: fetch urls, fix #67

[hanspagel]

With this PR references to URLs can be resolved.

To achieve this, I’ve introduced the new utility load utility, which imports JSON stings, YAML strings, JS objects, files and urls now. It even comes with a tiny plugin API, which means you can add whatever data source you’d like, or not enable file support (in browser envs).

I’ve had to make the load utility async, which made the pipeline syntax really ugly (await (await openapi().load()).resolve()), so I’ve refactored it to put all actions in a queue and work through it at the end, which enables a way nicer syntax:

Pipeline syntax

import { openapi, fetchUrlsPlugin, readFilesPlugin } from '@scalar/openapi-parser'

const result = await openapi()
  .load('./openapi.yaml', {
    plugins: [readFilesPlugin, fetchUrlsPlugin],
  })
  .dereference()
  .get()

Modular syntax

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)

Additional improvements

• fixed add loose types #67 to account for random user input
• openapi().load(…).files() to retrieve the whole filesystem
• improved error messages (they all used to start with “: ”)

Example

{
  "openapi": "3.1.0",
  "info": {
    "title": "HTTP Reference"
  },
  "paths": {
    "/foobar": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json#/components/schemas/Planet"
              }
            }
          }
        }
      }
    }
  }
}

[changeset-bot]

🦋 Changeset detected

Latest commit: 78cd843

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@scalar/openapi-parser	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[relativeci]

#44 Bundle Size — 477.72KiB (-0.58%).

78cd843(current) vs e3d7bba main#42(baseline)

Bundle metrics   3 changes 1 improvement

	Current #44	Baseline #42
Initial JS	477.72KiB(-0.58%)	480.51KiB
Initial CSS	0B	0B
Cache Invalidation	100%	0%
Chunks	1	1
Assets	1	1
Modules	306(+0.33%)	305
Duplicate Modules	0	0
Duplicate Code	0%	0%
Packages	10	10
Duplicate Packages	0	0

Bundle size by type   1 change 1 improvement

	Current #44	Baseline #42
JS	477.72KiB (-0.58%)	480.51KiB

---

Bundle analysis report Branch feat/fetch-urls Project dashboard