Docs Quickstart  //  Join us on Slack

OpenAPI

A set of packages and tools for working with OpenAPI Specification documents.
Used directly in Speakeasy's product to power our SDK Generation and Gram products.

Main Packages

arazzo

The arazzo package provides an API for working with Arazzo documents including reading, creating, mutating, walking and validating them.

openapi

The openapi package provides an API for working with OpenAPI documents including reading, creating, mutating, walking, validating and upgrading them. Supports OpenAPI 3.0.x, 3.1.x, and 3.2.x specifications.

swagger

The swagger package provides an API for working with Swagger 2.0 documents including reading, creating, mutating, walking, validating, and upgrading them to OpenAPI 3.0.

overlay

The overlay package provides an API for working with OpenAPI Overlays including applying overlays to specifications, comparing specifications to generate overlays, and validating overlay documents.

CLI Tool

This repository also provides a comprehensive CLI tool for working with OpenAPI specifications, Arazzo workflows, and OpenAPI overlays.

Installation

Homebrew (macOS/Linux):

brew install openapi

Go Install:

go install github.com/speakeasy-api/openapi/cmd/openapi@latest

Script Installation:

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.sh | bash

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/speakeasy-api/openapi/main/scripts/install.ps1 | iex

For manual installation, upgrade instructions, custom installation options, and troubleshooting, see the detailed installation guide.

Usage

The CLI provides four main command groups:

• openapi spec - Commands for working with OpenAPI specifications (documentation)

  • bootstrap - Create a new OpenAPI document with best practice examples
  • bundle - Bundle external references into components section
  • clean - Remove unused components and unused top-level tags from an OpenAPI specification
  • explore - Interactively explore an OpenAPI specification in the terminal
  • inline - Inline all references in an OpenAPI specification
  • join - Join multiple OpenAPI documents into a single document
  • localize - Localize an OpenAPI specification by copying external references to a target directory
  • optimize - Optimize an OpenAPI specification by deduplicating inline schemas
  • sanitize - Remove unwanted elements from an OpenAPI specification
  • snip - Remove selected operations from an OpenAPI specification (interactive or CLI)
  • upgrade - Upgrade an OpenAPI specification to the latest supported version
  • validate - Validate an OpenAPI specification document

• openapi swagger - Commands for working with Swagger 2.0 documents (documentation)

  • validate - Validate a Swagger 2.0 specification document
  • upgrade - Upgrade a Swagger 2.0 specification to OpenAPI 3.0

• openapi arazzo - Commands for working with Arazzo workflow documents (documentation)

  • validate - Validate an Arazzo workflow document

• openapi overlay - Commands for working with OpenAPI overlays (documentation)

  • apply - Apply an overlay to an OpenAPI specification
  • compare - Compare two specifications and generate an overlay describing differences
  • validate - Validate an OpenAPI overlay document

Quick Examples

# Validate an OpenAPI specification
openapi spec validate ./spec.yaml

# Bundle external references into components section
openapi spec bundle ./spec.yaml ./bundled-spec.yaml

# Inline all references to create a self-contained document
openapi spec inline ./spec.yaml ./inlined-spec.yaml

# Upgrade OpenAPI spec to latest version
openapi spec upgrade ./spec.yaml ./upgraded-spec.yaml

# Apply an overlay to a specification
openapi overlay apply --overlay overlay.yaml --schema spec.yaml

# Validate an Arazzo workflow document
openapi arazzo validate ./workflow.arazzo.yaml

# Validate a Swagger 2.0 document
openapi swagger validate ./api.swagger.yaml

# Upgrade Swagger 2.0 to OpenAPI 3.0
openapi swagger upgrade ./api.swagger.yaml ./openapi.yaml

For detailed usage instructions for each command group, see the individual documentation linked above.

Sub Packages

This repository also contains a number of sub packages that are used by the main packages to provide the required functionality. The below packages may be moved into their own repository in the future, depending on future needs.

json

The json package provides utilities for converting between JSON and YAML.

jsonpointer

The jsonpointer package provides an API for working with RFC 6901 compliant JSON Pointers. Providing functionality for validating JSON Pointers, and extracting the target of a JSON Pointer for various Go types and structures.

jsonschema

The jsonschema package provides various models for working with the different JSON Schema dialects.

sequencedmap

The sequencedmap package provides a map implementation that maintains the order of keys as they are added.

Contributing

This repository is maintained by Speakeasy, but we welcome and encourage contributions from the community to help improve its capabilities and stability.

How to Contribute

1. Discussions: Have a feature request or want to discuss the roadmap? Use GitHub Discussions to share your ideas and engage with the community.

2. Issues: Found a bug or technical issue? Open a GitHub Issue to report it with details about the problem.

3. Pull Requests: We welcome pull requests! If you'd like to contribute code:

   • Fork the repository
   • Create a new branch for your feature/fix
   • Submit a PR with a clear description of the changes and any related issues

4. Feedback: Share your experience using the packages or suggest improvements.

Getting Started: Look for items tagged with "good first issue" in both Discussions and Issues if you want to pick up something to work on.

All contributions, whether they're feature requests, bug reports, or code changes, help make this project better for everyone.

Please ensure your contributions adhere to our coding standards and include appropriate tests where applicable.