openapi

README

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 both OpenAPI 3.0.x and 3.1.x specifications.

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

Install the CLI tool using Homebrew:

brew install openapi

Install the CLI tool using Go:

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

Usage

The CLI provides three 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 from an OpenAPI specification
  • inline - Inline all references in an OpenAPI specification
  • join - Join multiple OpenAPI documents into a single document
  • optimize - Optimize an OpenAPI specification by deduplicating inline schemas
  • upgrade - Upgrade an OpenAPI specification to the latest supported version
  • validate - Validate an OpenAPI specification document

• 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

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. Open Issues: Found a bug or have a feature suggestion? Open an issue to describe what you'd like to see changed.

2. 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

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

All contributions, whether they're bug reports, feature requests, 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.