api-ref-bundler is a JavaScript/TypeScript utility library designed to resolve and consolidate all external and internal `$ref` references within JSON-based API documents. It supports a wide range of specification formats including JsonSchema, Swagger 2.x, OpenAPI 3.x, AsyncAPI 2.x, and AsyncAPI 3.x. The current stable version is 0.5.1, with recent updates focusing on performance and new specification support, notably AsyncAPI v3.x. Key differentiators include its zero-dependency footprint, browser and Node.js compatibility, explicit handling of circular references, and a resolver-agnostic design, requiring users to provide their own logic for reading and parsing source paths. This approach offers flexibility but also shifts the responsibility for file I/O and deserialization to the developer. It ships with full TypeScript support.
npm install api-ref-bundlerVerified import paths — ran on the pinned version, not inferred.
Demonstrates how to use `bundle` and `dereference` functions with a custom file system resolver for API documents, including handling of Markdown references and error hooks, using mock files for a runnable example.
Thoroughly test existing AsyncAPI 2.x documents after upgrading. If encountering issues, refer to the AsyncAPI v3 specification for structural changes and adjust your input documents or custom resolver logic accordingly.
Implement a robust `resolver` function that takes a `sourcePath` string and returns the parsed content (object for JSON, string for Markdown/text). Ensure it handles file system lookups, network requests, or any other data source your application uses.
If your documents contain circular references and you want them to be resolved into their respective nodes during dereferencing, set `enableCircular: true` in the `DereferenceOptions`. Otherwise, implement `onCycle` hook to handle them gracefully.
Carefully consider the `ignoreSibling` option based on your specification's requirements. For OpenAPI/Swagger documents where `$ref` typically stands alone, `ignoreSibling: true` is usually appropriate. For other JSON Schema use cases where `$ref` can co-exist with other properties, ensure this option is set correctly (e.g., `false` or omitted if you want to merge).
Ensure your project is configured for ESM. If using Node.js, add `"type": "module"` to your `package.json` or use `.mjs` file extension. If using a bundler (e.g., Webpack, Rollup), verify its configuration for handling ESM imports. As a workaround for CommonJS, you might try `const { bundle } = await import('api-ref-bundler');` for dynamic ESM import.Double-check the `sourcePath` being passed to the `resolver` and ensure the file exists. Verify that `path.join` (if used in your resolver) constructs the correct absolute or relative path. Ensure your application has read permissions for the file system location.
Refine the logic within your `resolver` to correctly identify the content type based on file extension, MIME type, or content sniffing. Only apply `JSON.parse` to content confirmed to be JSON. For non-JSON content like Markdown, return it as a raw string as intended by the library.
If you want circular references to be converted into their respective nodes during dereferencing, set `enableCircular: true` in your `DereferenceOptions`. Alternatively, implement the `onCycle` hook within `DereferenceOptions` to provide custom logic for handling or reporting cyclic references without throwing an error.
No dependency data recorded yet.