https://github.com/stackql/deno-openapi-dereferencer
https://github.com/stackql/deno-openapi-dereferencer
Last synced: 10 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/stackql/deno-openapi-dereferencer
- Owner: stackql
- Created: 2024-11-15T02:28:07.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-11-15T21:04:10.000Z (about 1 year ago)
- Last Synced: 2025-01-21T22:43:08.217Z (12 months ago)
- Language: TypeScript
- Size: 84 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# @stackql/deno-openapi-dereferencer
A Deno module to recursively dereference and flatten OpenAPI specifications. This module provides functions to handle `$ref`, `allOf`, `oneOf`, and `anyOf` structures, creating a fully dereferenced and optionally flattened document.
See the project on [__jsr__](https://jsr.io/@stackql/deno-openapi-dereferencer) for more info.
## Features
- **Full dereferencing**: Resolves all `$ref` references within an OpenAPI specification.
- **Flattening**: Merges `allOf` schemas into a single object.
- **Selective processing**: Allows dereferencing from a specific path within the document.
- **Path-based exclusion**: Optionally skip dereferencing for specific paths within the document using `ignorePaths`.
## Usage
### Importing the Module
To use the module, import it from Deno Land:
```typescript
import {
dereferenceApi,
flattenAllOf,
selectFirstOfOneOf,
selectFirstOfAnyOf
} from "jsr:@stackql/deno-openapi-dereferencer";
```
### Example Usage
#### Fully Dereference an OpenAPI Document
```typescript
import { dereferenceApi } from "jsr:@stackql/deno-openapi-dereferencer";
const apiDoc = await Deno.readTextFile("./path/to/openapi.yaml");
const dereferencedDoc = await dereferenceApi(apiDoc);
console.log(dereferencedDoc);
```
#### Flatten `allOf` Properties
```typescript
import { flattenAllOf } from "jsr:@stackql/deno-openapi-dereferencer";
const flattenedDoc = await flattenAllOf(dereferencedDoc);
console.log(flattenedDoc);
```
#### Selective Dereferencing with Ignore Paths
```typescript
import { dereferenceApi } from "jsr:@stackql/deno-openapi-dereferencer";
const apiDoc = await Deno.readTextFile("./path/to/openapi.yaml");
const ignorePaths = ["$.components.x-stackQL-resources"]; // Exclude specific paths
const dereferencedDoc = await dereferenceApi(apiDoc, "$", ignorePaths);
console.log(dereferencedDoc);
```
### Functions
- **`dereferenceApi(apiDoc: any, startAt: string = "$", ignorePaths?: string[]): Promise`**
Dereferences `$ref` properties from a specified path in the OpenAPI document.
- **Parameters:**
- `apiDoc`: The OpenAPI document object to be dereferenced.
- `startAt` (optional): JSONPath to specify the starting point for dereferencing. Defaults to the root (`"$"`).
- `ignorePaths` (optional): Array of JSONPath expressions. Any `$ref` found in these paths will be ignored.
- **Returns**: The fully dereferenced document.
- **`flattenAllOf(apiDoc: any): Promise`**
Flattens `allOf` properties in an OpenAPI document, merging schemas into a single object.
- **Parameters:**
- `apiDoc`: The OpenAPI document object to be flattened.
- **Returns**: The document with `allOf` properties flattened.
- **`selectFirstOfOneOf(apiDoc: any): Promise`**
Simplifies `oneOf` arrays by selecting the first schema.
- **Parameters:**
- `apiDoc`: The OpenAPI document object to process.
- **Returns**: The document with `oneOf` arrays simplified.
- **`selectFirstOfAnyOf(apiDoc: any): Promise`**
Simplifies `anyOf` arrays by selecting the first schema.
- **Parameters:**
- `apiDoc`: The OpenAPI document object to process.
- **Returns**: The document with `anyOf` arrays simplified.
## Testing
Run tests using Deno’s testing suite:
```bash
deno test --allow-read
```
## License
MIT License.