Working with Large Specs

Working with Large Specs

When working with real-world REST APIs, the number of paths and schemas can grow quickly—especially if you add detailed descriptions and examples.

In OpenAPI, this creates a challenge: the specification file can become thousands of lines long, making it difficult to manage. For reference, large APIs such as Stripe and GitHub reach hundreds of thousands of lines.

Editing such massive YAML files by hand is inefficient and unpleasant 🙄

Breaking Down the Specification

OpenAPI supports splitting specifications into multiple files by referencing schemas and paths with $ref.

This allows you to structure your API specification as a collection of smaller, maintainable files that can be composed into a single OpenAPI document.

👉 We highly encourage using $ref to make your specifications easier to maintain.

Bundling for Tools

Many tools (including Framna Docs) expect a single OpenAPI file as input.
To go from multiple source files to one specification, you’ll need to use a process called bundling.

We recommend Redocly’s CLI for this task.

Here’s a sample script that bundles your OpenAPI files:

bundle.sh

#!/bin/bash
set -e

npx -y @redocly/cli bundle ./src/openapi.yml -o ./openapi-bundle.yml

We run this script before committing changes to the -openapi repository. Then, we configure Framna Docs to use openapi-bundle.yml as the default specification via the defaultSpecificationName parameter.

$./bundle.sh
bundling src/openapi.yml...
📦 Created a bundle for src/openapi.yml at openapi-bundle.yml 9ms.

🪄 Pro Tip: Git Hook Integration

Add a pre-push Git hook that runs the bundling step automatically. This ensures your latest changes are always bundled before pushing to the repository.

.githooks/pre-push

#!/bin/bash

# Run the bundle command
echo "Running bundle..."
./bundle.sh

# Check if the bundle command was successful
if [ $? -ne 0 ]; then
  echo "Bundle command failed. Aborting push."
  exit 1
fi

# Check if the bundle file was updated
if git diff --quiet openapi-bundle.yml; then
  echo "Bundle command succeeded. Proceeding with push."
else
  echo "Warning: The bundle file 'openapi-bundle.yml' was updated. Please commit the changes before pushing."
  exit 1
fi

Install with

git config core.hooksPath .githooks

Getting started

There's a starter repository right here: https://github.com/shapehq/starter-openapi-bundled to get you going 🚀