https://github.com/speakeasy-api/openapi
A set of packages and tools for working with OpenAPI and Arazzo Specification documents.
https://github.com/speakeasy-api/openapi
arazzo golang openapi
Last synced: 4 days ago
JSON representation
A set of packages and tools for working with OpenAPI and Arazzo Specification documents.
- Host: GitHub
- URL: https://github.com/speakeasy-api/openapi
- Owner: speakeasy-api
- License: mit
- Created: 2024-08-22T08:59:55.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-30T05:10:58.000Z (7 months ago)
- Last Synced: 2025-07-22T02:04:00.575Z (6 months ago)
- Topics: arazzo, golang, openapi
- Language: Go
- Homepage:
- Size: 339 KB
- Stars: 19
- Watchers: 6
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
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](./arazzo)
The `arazzo` package provides an API for working with Arazzo documents including reading, creating, mutating, walking and validating them.
### [openapi](./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](./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](./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):**
```bash
brew install openapi
```
**Go Install:**
```bash
go install github.com/speakeasy-api/openapi/cmd/openapi@latest
```
**Script Installation:**
Linux/macOS:
```bash
curl -fsSL https://go.speakeasy.com/openapi.sh | bash
```
Windows (PowerShell):
```powershell
iwr -useb https://go.speakeasy.com/openapi.ps1 | iex
```
For manual installation, upgrade instructions, custom installation options, and troubleshooting, see the [detailed installation guide](./INSTALL.md).
### Usage
The CLI provides four main command groups:
- **`openapi spec`** - Commands for working with OpenAPI specifications ([documentation](./cmd/openapi/commands/openapi/README.md))
- `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](./cmd/openapi/commands/swagger/README.md))
- `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](./cmd/openapi/commands/arazzo/README.md))
- `validate` - Validate an Arazzo workflow document
- **`openapi overlay`** - Commands for working with OpenAPI overlays ([documentation](./cmd/openapi/commands/overlay/README.md))
- `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
```bash
# 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](./json)
The `json` package provides utilities for converting between JSON and YAML.
### [jsonpointer](./jsonpointer)
The `jsonpointer` package provides an API for working with [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901) compliant JSON Pointers. Providing functionality for validating JSON Pointers, and extracting the target of a JSON Pointer for various Go types and structures.
### [jsonschema](./jsonschema)
The `jsonschema` package provides various models for working with the different JSON Schema dialects.
### [sequencedmap](./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](https://github.com/speakeasy-api/openapi/discussions) to share your ideas and engage with the community.
2. **Issues**: Found a bug or technical issue? Open a [GitHub Issue](https://github.com/speakeasy-api/openapi/issues) 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](https://github.com/speakeasy-api/openapi/discussions) and [Issues](https://github.com/speakeasy-api/openapi/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.