api-ref-bundler

!GitHub Workflow Status (with event)

This package provides utils to resolve all external/internal references in Json based API document and bundle/dereference into single document

Works perfectly with API specifications

- JsonSchema
- Swagger 2.x
- OpenApi 3.x
- AsyncApi 2.x
- AsyncApi 3.x

Features

- bundle all external refs in signle document
- converts external references into internal
- support full and partial dereference
- support external '.md' references
- support for all kinds of circularity
- no concept of resolvers - you are in charge of the whole reading & path parsing process
- no parser included - bring your own!
- Typescript syntax support out of the box
- No dependencies, can be used in nodejs or browser

Installation

``SH
npm install api-ref-bundler --save
`

Usage

$3

`ts
import { promises as fs } from 'fs'
import { bundle, dereference } from 'api-ref-bundler'

const resolver = async (sourcePath) => {
const data = await fs.readFile(path.join(__dirname, "./", sourcePath), "utf8")
return sourcePath.slice(-3) === ".md" ? data : JSON.parse(data)
}

// bundle (convert all external refs to internal)
bundle("schema.json", resolver, { ignoreSibling: true }).then(schema => {
console.log(schema)
}).catch(errors => {
console.log(errors)
})

const onErrorHook = (msg: string) => {
throw new Error(msg)
}

// full dereference (remove all refs)
dereference("schema.json", resolver, { hooks: { onError: onErrorHook }}).then(schema => {
console.log(schema)
}).catch(errors => {
console.log(errors)
})

// partial dereference (remove all refs in path '/properties/foo')
dereference("schema.json#/properties/foo", resolver).then(foo => {
console.log(foo)
}).catch(errors => {
console.log(errors)
})

`

#### Bundle options
`ts
interface BundleOptions {
ignoreSibling?: boolean // ignore $ref sibling content
hooks?: {
onError?: (message: string, ctx: BundleContext) => void // error hook
onRef?: (ref: string, ctx: BundleContext) => void // ref hook
onCrawl?: (value: any, ctx: BundleContext) => void // node crawl hook
onExit?: (value: any, ctx: BundleContext) => void // node crawl exit hook
}
}
`

#### Dereference options
`ts
interface DereferenceOptions {
ignoreSibling?: boolean // ignore $ref sibling content
fullCrawl?: boolean // crawl all nodes includin cached
enableCircular?: boolean // convert circular $refs to nodes
hooks?: {
onError?: (message: string, ctx: DereferenceContext) => void // error hook
onRef?: (ref: string, ctx: DereferenceContext) => void // ref hook
onCrawl?: (value: any, ctx: DereferenceContext) => void // node crawl hook
onExit?: (value: any, ctx: DereferenceContext) => void // node crawl exit hook
onCycle?: (ref: string, ctx: DereferenceContext) => void // cycle refs hook
}
}
`

$3

A browser version of api-ref-bundler is also available via CDN:
`html

`

Reference api-ref-bundler in your HTML and use the global variable ApiRefBundler.
`HTML

`

Contributing


When contributing, keep in mind that it is an objective of api-ref-bundler to have no package dependencies. This may change in the future, but for now, no-dependencies.

Please run the unit tests before submitting your PR: npm test`. Hopefully your PR includes additional unit tests to illustrate your change/modification!

License

MIT