# release-oss-openapi-library
Source: https://speakeasy.com/blog/release-oss-openapi-library


import { CodeWithTabs } from "@/mdx/components";

Today we're excited to announce the release of our OpenAPI parser library — a comprehensive Go library for working with OpenAPI 3.0.x and 3.1.x specifications, Arazzo workflow descriptions, and OpenAPI Overlay files that has been battle-tested on thousands of real-world API specs.

[Check it out on GitHub →](https://github.com/speakeasy-api/openapi)

## Why we built this parser

At Speakeasy, we process thousands of OpenAPI specifications from companies across all industries and sizes through our core SDK generation platform. More recently, through [Gram](https://app.getgram.ai) — our platform for building MCP (Model Context Protocol) servers — we've encountered even more diverse specifications in varying states of completeness and correctness.

These specs come in all shapes and conditions — some perfectly valid, others with quirks, gaps, or outright errors that need to be handled gracefully. Gram, in particular, has been a catalyst for pushing our parsing capabilities further, as it needs to work reliably with imperfect specifications while automatically generating functional MCP servers.

We needed a parser that could work with imperfect specs while providing the tools to improve them over time. This is especially important for API tooling that helps developers enhance their specifications incrementally, whether they're generating SDKs or building MCP servers.

## Core capabilities

The library provides comprehensive functionality for working with OpenAPI documents:

- **Parsing and validation**: Full support for OpenAPI 3.0.x and 3.1.x with built-in validation
- **Document traversal**: Powerful walking API to iterate through specific elements
- **Reference resolution**: Intelligent handling of `$ref` references, including circular references
- **Document manipulation**: Create, modify, and transform OpenAPI documents programmatically
- **Upgrading**: Automatically upgrade OpenAPI 3.0.x documents to 3.1.x
- **Type safety**: Strongly typed Go structs that closely mirror the OpenAPI specification

## Getting started

Here are some examples of what you can do with the parser:

<CodeWithTabs
  tabs={[
    {
      label: "parse.go",
      language: "go",
      code: `package main

import (
    "context"
    "fmt"
    "os"

    "github.com/speakeasy-api/openapi/openapi"

)

func main() {
ctx := context.Background()

    r, err := os.Open("./openapi.yaml")
    if err != nil {
    	panic(err)
    }
    defer r.Close()

    // Unmarshal the OpenAPI document which will also validate it against the OpenAPI Specification
    doc, validationErrs, err := openapi.Unmarshal(ctx, r /*, openapi.WithSkipValidation()*/) // Optionally skip validation
    if err != nil {
    	panic(err)
    }

    // Validation errors are returned separately from any errors that block the document from being unmarshalled
    // allowing an invalid document to be mutated and fixed before being marshalled again
    for _, err := range validationErrs {
    	fmt.Println(err.Error())
    }

    fmt.Printf("OpenAPI Version: %s\\n", doc.OpenAPI)
    fmt.Printf("API Title: %s\\n", doc.Info.Title)
    fmt.Printf("API Version: %s\\n", doc.Info.Version)

}`,
    },
    {
      label: "walk.go",
      language: "go",
      code: `package main

import (
    "context"
    "fmt"
    "os"

    "github.com/speakeasy-api/openapi/jsonschema/oas3"
    "github.com/speakeasy-api/openapi/openapi"
    "github.com/speakeasy-api/openapi/walk"

)

func main() {
ctx := context.Background()

    f, err := os.Open("./openapi.yaml")
    if err != nil {
    	panic(err)
    }
    defer f.Close()

    doc, _, err := openapi.Unmarshal(ctx, f)
    if err != nil {
    	panic(err)
    }

    operationCount := 0

    // Walk through the document using the iterator API
    for item := range openapi.Walk(ctx, doc) {
    	// Use the matcher to handle different types of objects
    	err := item.Match(openapi.Matcher{
    		OpenAPI: func(o *openapi.OpenAPI) error {
    			fmt.Printf("Found OpenAPI document: %s\\n", o.Info.Title)
    			return nil
    		},
    		Info: func(info *openapi.Info) error {
    			fmt.Printf("Found Info: %s (version %s)\\n", info.Title, info.Version)
    			return nil
    		},
    		Operation: func(op *openapi.Operation) error {
    			if op.OperationID != nil {
    				fmt.Printf("Found Operation: %s\\n", *op.OperationID)
    			}
    			operationCount++
    			// Terminate after finding 2 operations
    			if operationCount >= 2 {
    				return walk.ErrTerminate
    			}
    			return nil
    		},
    		Schema: func(schema *oas3.JSONSchema[oas3.Referenceable]) error {
    			if schema.IsLeft() && schema.GetLeft().Type != nil {
    				types := schema.GetLeft().GetType()
    				if len(types) > 0 {
    					fmt.Printf("Found Schema of type: %s\\n", types[0])
    				}
    			}
    			return nil
    		},
    	})
    	if err != nil {
    		if err == walk.ErrTerminate {
    			fmt.Println("Walk terminated early")
    			break
    		}
    		fmt.Printf("Error during walk: %s\\n", err.Error())
    		break
    	}
    }

}`,
    },
    {
      label: "mutate.go",
      language: "go",
      code: `package main

import (
    "bytes"
    "context"
    "fmt"
    "os"

    "github.com/speakeasy-api/openapi/openapi"
    "github.com/speakeasy-api/openapi/pointer"

)

func main() {
ctx := context.Background()

    r, err := os.Open("./openapi.yaml")
    if err != nil {
    	panic(err)
    }
    defer r.Close()

    // Unmarshal the OpenAPI document
    doc, validationErrs, err := openapi.Unmarshal(ctx, r)
    if err != nil {
    	panic(err)
    }

    // Print any validation errors
    for _, err := range validationErrs {
    	fmt.Println(err.Error())
    }

    // Mutate the document by modifying the returned OpenAPI object
    doc.Info.Title = "Updated Simple API"
    doc.Info.Description = pointer.From("This API has been updated with new description")

    // Add a new server
    doc.Servers = append(doc.Servers, &openapi.Server{
    	URL:         "https://api.updated.com/v1",
    	Description: pointer.From("Updated server"),
    })

    buf := bytes.NewBuffer([]byte{})

    // Marshal the updated document
    if err := openapi.Marshal(ctx, doc, buf); err != nil {
    	panic(err)
    }

    fmt.Println("Updated document:")
    fmt.Println(buf.String())

}`,
}
]}
/>

## Advanced features

The parser includes several advanced capabilities that set it apart:

**Lazy reference resolution**: References are resolved on-demand, giving you fine-grained control over when and how references are loaded. This improves performance when working with large documents where you only need specific parts.

**Circular reference handling**: Properly detects and handles circular references in schemas without infinite loops or stack overflow errors.

**Extension support**: Full support for OpenAPI extensions (`x-*` fields) with type-safe access patterns.

**Memory efficiency**: Optimized for working with large specifications while using minimal memory, important when processing hundreds of documents.

## Beyond OpenAPI: Arazzo and Overlays

While OpenAPI documents define individual API endpoints, this library also supports two important extensions to the OpenAPI ecosystem:

**Arazzo workflow specifications** allow you to describe chains of API calls and complex workflows. Instead of just defining what endpoints exist, Arazzo lets you describe sequences like "authenticate → create user → get user → delete user" where the output of one call feeds into the inputs of another. This is particularly powerful for testing API workflows and building integrations across multiple services.

**OpenAPI Overlays** provide a way to modify existing OpenAPI documents without directly editing the original files. Overlays are separate documents containing instructions for updating, adding, or removing parts of an OpenAPI specification. This is invaluable for managing different versions of your API documentation, applying organization-specific customizations, or maintaining separate internal and external versions of your API specs.

Both specifications integrate seamlessly with the core OpenAPI parsing functionality, giving you a complete toolkit for working with modern API specifications.

## What's next

This release represents our foundational parsing capabilities across the OpenAPI ecosystem, but we have exciting plans ahead:

- Enhanced tooling integration with our CLI for validation and transformation workflows
- Additional utilities for common manipulation tasks across all supported specifications
- Support for emerging OpenAPI specification features as they're released
- Community-driven improvements and extensions

## Open source and community-driven

This library is fully open source and we welcome contributions from the community. Whether it's bug reports, feature requests, or pull requests, we're excited to collaborate with developers who are building the future of API tooling.

The codebase has been designed with contributors in mind — clean architecture, comprehensive tests, and clear documentation make it easy to understand and extend.

## Try it out

The OpenAPI parser is available now on GitHub. Get started by checking out our documentation and examples, and let us know what you build with it!

We're excited to see how the community uses this library to build better API tooling. This release represents years of learning from real-world API specifications, and we can't wait to see what innovative solutions the community creates with it.