OpenAPI Composition

This project is responsible for compiling various OpenAPI schema definitions into a single "root level" OpenAPI specification.

The goal is to provide a simple, single-purpose tool that lets developers more easily split a large OpenAPI specification into a series of smaller files while automatically maintaining the root-level document's references.

Requirements

• Node.js >= v20.12.0

Installation

yarn add --dev @altearius/openapi-compose

Usage

This package makes specific assumptions about how a project is structured.

The CLI command accepts a single argument: a path to a template file used to generate the root level OpenAPI specification.

yarn openapi-compose ./openapi.template.yaml

The template file should can be any OpenAPI file, either JSON or YAML, but it should contain an $imports property that is an array of glob patterns that will be used to find other OpenAPI files to include in the root level OpenAPI specification:

# ./openapi.template.yaml
openapi: 3.1.0
paths:
  $imports: ['**/openapi.yaml']

# ./sub-folder/openapi.yaml (in a nested directory)
openapi: 3.1.0
paths:
  /sub-folder:
    get:
      responses:
        '200': { description: OK }

The generated result will be a single OpenAPI specification file that contains all of the path definitions from the imported files. The $imports property is replaced with references to each of the located files:

# ./openapi.yaml (generated by the build command as a sibling to the template)
openapi: 3.1.0
paths:
  /sub-folder:
    $ref: ./sub-folder/openapi.yaml#/paths/~1sub-folder

Imports that themselves use $ref to reference other files are supported. The resulting $ref will be updated to point to the correct location in the generated file.

API

An API is also provided:

import { Compose, ComposeAndWrite } from '@altearius/openapi-compose';

// Compose processes the template file and returns the composed OpenAPI object
// without writing it to disk. You have to give it the path to the template
// to read and a path to the final file to write (used to render paths as
// relative to the final template). You may optionally provide a logging
// function as the final paramter (`console` will be used if omitted).
const composed = await Compose(
  './api/openapi.template.yaml',
  './api/openapi.yaml',
  console // (optional)
);

// At this point, you must "do something" with the final result, probably
// transform it some more or write it to the file system.
//
// Alternatively, you can use the `ComposeAndWrite` function go ahead and
// render the final result to the disk as a YAML document.
await ComposeAndWrite('./api/openapi.template.yaml', './api/openapi.yaml');

Contributing

The following developer scripts are provided:

• build: Build the project.
• clean: Remove build artifacts.
• lint: Run ESLint.
• pretty: Check formatting using prettier.
• test: Run tests.