libopenapi

README

libopenapi - enterprise grade OpenAPI tools for golang.

libopenapi has full support for Swagger (OpenAPI 2), OpenAPI 3, and OpenAPI 3.1. It can handle the largest and most complex specifications you can think of.

---

Sponsors & users

If your company is using libopenapi, please considering supporting this project, like our very kind sponsors:

Speakeasy

scalar

---

libopenapi is pretty new, so our list of notable projects that depend on libopenapi is small (let me know if you'd like to add your project)

• github.com/daveshanley/vacuum - "The world's fastest and most scalable OpenAPI/Swagger linter/quality tool"
• github.com/pb33f/openapi-changes - "The world's sexiest OpenAPI breaking changes detector"
• github.com/pb33f/wiretap - "The world's coolest OpenAPI compliance analysis tool"
• github.com/danielgtaylor/restish - "Restish is a CLI for interacting with REST-ish HTTP APIs"
• github.com/speakeasy-api/speakeasy - "Speakeasy CLI makes validating OpenAPI docs and generating idiomatic SDKs easy!"
• github.com/apicat/apicat - "AI-powered API development tool"
• github.com/mattermost/mattermost - "Software development lifecycle platform"
• Your project here?

---

Come chat with us

Need help? Have a question? Want to share your work? Join our discord and come say hi!

Check out the libopenapi-validator

Need to validate requests, responses, parameters or schemas? Use the new libopenapi-validator module.

Documentation

See all the documentation at https://pb33f.io/libopenapi/

• Installing libopenapi
• Using OpenAPI
• Using Swagger
• The Data Model
• Validation
• Modifying / Mutating the OpenAPI Model
• Mocking / Creating Examples
• Using Vendor Extensions
• The Index
• The Resolver
• The Rolodex
• Circular References
• What Changed / Diff Engine
• FAQ
• About libopenapi

Read the go docs at https://pkg.go.dev/github.com/pb33f/libopenapi

---

Quick-start tutorial

👀 Get rolling fast using libopenapi with the Parsing OpenAPI files using go guide 👀

Read the full docs at https://pkg.go.dev

---

Logo gopher is modified, originally from egonelbre

Documentation

Overview

Package libopenapi is a library containing tools for reading and in and manipulating Swagger (OpenAPI 2) and OpenAPI 3+ specifications into strongly typed documents. These documents have two APIs, a high level (porcelain) and a low level (plumbing).

Every single type has a 'GoLow()' method that drops down from the high API to the low API. Once in the low API, the entire original document data is available, including all comments, line and column numbers for keys and values.

There are two steps to creating a using Document. First, create a new Document using the NewDocument() method and pass in a specification []byte array that contains the OpenAPI Specification. It doesn't matter if YAML or JSON are used.

Index

• func CompareDocuments(original, updated Document) (*model.DocumentChanges, []error)
• type Document
  • func NewDocument(specByteArray []byte) (Document, error)
  • func NewDocumentWithConfiguration(specByteArray []byte, configuration *datamodel.DocumentConfiguration) (Document, error)
  • func NewDocumentWithTypeCheck(specByteArray []byte, bypassCheck bool) (Document, error)
• type DocumentModel

Examples

• NewDocument (FromOpenAPI3Document)
• NewDocument (FromSwaggerDocument)
• NewDocument (FromUnknownVersion)
• NewDocument (FromWithDocumentConfigurationFailure)
• NewDocument (FromWithDocumentConfigurationSuccess)
• NewDocument (Infinite_circular_references)
• NewDocument (ModifyAndReRender)
• NewDocument (MutateValuesAndSerialize)
• NewDocument (Unpacking_extensions)

Functions

func CompareDocuments

func CompareDocuments(original, updated Document) (*model.DocumentChanges, []error)

CompareDocuments will accept a left and right Document implementing struct, build a model for the correct version and then compare model documents for changes.

If there are any errors when building the models, those errors are returned with a nil pointer for the model.DocumentChanges. If there are any changes found however between either Document, then a pointer to model.DocumentChanges is returned containing every single change, broken down, model by model.

Types

type Document

type Document interface {
	// GetVersion will return the exact version of the OpenAPI specification set for the document.
	GetVersion() string

	// GetRolodex will return the Rolodex instance that was used to load the document.
	GetRolodex() *index.Rolodex

	// GetSpecInfo will return the *datamodel.SpecInfo instance that contains all specification information.
	GetSpecInfo() *datamodel.SpecInfo

	// SetConfiguration will set the configuration for the document. This allows for finer grained control over
	// allowing remote or local references, as well as a BaseURL to allow for relative file references.
	SetConfiguration(configuration *datamodel.DocumentConfiguration)

	// GetConfiguration will return the configuration for the document. This allows for finer grained control over
	// allowing remote or local references, as well as a BaseURL to allow for relative file references.
	GetConfiguration() *datamodel.DocumentConfiguration

	// BuildV2Model will build out a Swagger (version 2) model from the specification used to create the document
	// If there are any issues, then no model will be returned, instead a slice of errors will explain all the
	// problems that occurred. This method will only support version 2 specifications and will throw an error for
	// any other types.
	BuildV2Model() (*DocumentModel[v2high.Swagger], []error)

	// BuildV3Model will build out an OpenAPI (version 3+) model from the specification used to create the document
	// If there are any issues, then no model will be returned, instead a slice of errors will explain all the
	// problems that occurred. This method will only support version 3 specifications and will throw an error for
	// any other types.
	BuildV3Model() (*DocumentModel[v3high.Document], []error)

	// RenderAndReload will render the high level model as it currently exists (including any mutations, additions
	// and removals to and from any object in the tree). It will then reload the low level model with the new bytes
	// extracted from the model that was re-rendered. This is useful if you want to make changes to the high level model
	// and then 'reload' the model into memory, so that line numbers and column numbers are correct and all update
	// according to the changes made.
	//
	// The method returns the raw YAML bytes that were rendered, and any errors that occurred during rebuilding of the model.
	// This is a destructive operation, and will re-build the entire model from scratch using the new bytes, so any
	// references to the old model will be lost. The second return is the new Document that was created, and the third
	// return is any errors hit trying to re-render.
	//
	// **IMPORTANT** This method only supports OpenAPI Documents. The Swagger model will not support mutations correctly
	// and will not update when called. This choice has been made because we don't want to continue supporting Swagger,
	// it's too old, so it should be motivation to upgrade to OpenAPI 3.
	RenderAndReload() ([]byte, Document, *DocumentModel[v3high.Document], []error)

	// Render will render the high level model as it currently exists (including any mutations, additions
	// and removals to and from any object in the tree). Unlike RenderAndReload, Render will simply print the state
	// of the model as it currently exists, and will not re-load the model into memory. It means that the low-level and
	// the high-level models will be out of sync, and the index will only be useful for the original document.
	//
	// Why use this instead of RenderAndReload?
	//
	// The simple answer is that RenderAndReload is a destructive operation, and will re-build the entire model from
	// scratch using the new bytes, which is desirable if you want to make changes to the high level model and then
	// 'reload' the model into memory, so that line numbers and column numbers are correct and the index is accurate.
	// However, if you don't care about the low-level model, and you're not using the index, and you just want to
	// print the state of the model as it currently exists, then Render() is the method to use.
	// **IMPORTANT** This method only supports OpenAPI Documents.
	Render() ([]byte, error)

	// Serialize will re-render a Document back into a []byte slice. If any modifications have been made to the
	// underlying data model using low level APIs, then those changes will be reflected in the serialized output.
	//
	// It's important to know that this should not be used if the resolver has been used on a specification to
	// for anything other than checking for circular references. If the resolver is used to resolve the spec, then this
	// method may spin out forever if the specification backing the model has circular references.
	// Deprecated: This method is deprecated and will be removed in a future release. Use RenderAndReload() instead.
	// This method does not support mutations correctly.
	Serialize() ([]byte, error)
}

Document Represents an OpenAPI specification that can then be rendered into a model or serialized back into a string document after being manipulated.

func NewDocument

func NewDocument(specByteArray []byte) (Document, error)

NewDocument will create a new OpenAPI instance from an OpenAPI specification []byte array. If anything goes wrong when parsing, reading or processing the OpenAPI specification, there will be no document returned, instead a slice of errors will be returned that explain everything that failed.

After creating a Document, the option to build a model becomes available, in either V2 or V3 flavors. The models are about 70% different between Swagger and OpenAPI 3, which is why two different models are available.

This function will automatically follow (meaning load) any file or remote references that are found anywhere. Which means recursively also, like a spider, it will follow every reference found, local or remote.

If this isn't the behavior you want, or that you feel this is a potential security risk, then you can use the NewDocumentWithConfiguration() function instead, which allows you to set a configuration that will allow you to control if file or remote references are allowed.

Example (FromOpenAPI3Document)

Output:

There are 13 paths and 8 schemas in the document

Example (FromSwaggerDocument)

Output:

There are 14 paths and 6 schemas in the document

Example (FromUnknownVersion)

Output:

There are 5 paths and 6 schemas in the document

Example (FromWithDocumentConfigurationFailure)

Output:

There are 475 errors logged
Error building Digital Ocean spec errors reported

Example (FromWithDocumentConfigurationSuccess)

Output:

Digital Ocean spec built successfully

Example (Infinite_circular_references)

If you want to know more about circular references that have been found during the parsing/indexing/building of a document, you can capture the []errors thrown which are pointers to *resolver.ResolvingError

Output:

Journey: #/components/schemas/Two -> #/components/schemas/One -> #/components/schemas/Two
Loop Point: #/components/schemas/Two

Example (ModifyAndReRender)

Output:

There were 13 original paths. There are now 14 paths in the document
The original spec had 31143 bytes, the new one has 31213

Example (MutateValuesAndSerialize)

Output:

openapi: 3.1.0
info:
    title: A new title for a useless spec
    contact:
        name: Buckaroo
        email: buckaroo@pb33f.io
    license:
        url: https://pb33f.io/license

Example (Unpacking_extensions)

If you're using complex types with OpenAPI Extensions, it's simple to unpack extensions into complex types using `high.UnpackExtensions()`. libopenapi retains the original raw data in the low model (not the high) which means unpacking them can be a little complex.

This example demonstrates how to use the `UnpackExtensions` with custom OpenAPI extensions.

Output:

schemaOne 'x-custom-cakes' (some cakes) has 2 cakes, 'someCake' has 10 candles and blue frosting
parameterOne 'x-custom-burgers' (some burgers) has 2 burgers, 'anotherBurger' has mayo sauce and a lamb patty

func NewDocumentWithConfiguration

func NewDocumentWithConfiguration(specByteArray []byte, configuration *datamodel.DocumentConfiguration) (Document, error)

NewDocumentWithConfiguration is the same as NewDocument, except it's a convenience function that calls NewDocument under the hood and then calls SetConfiguration() on the returned Document.

func NewDocumentWithTypeCheck

func NewDocumentWithTypeCheck(specByteArray []byte, bypassCheck bool) (Document, error)

type DocumentModel

type DocumentModel[T v2high.Swagger | v3high.Document] struct {
	Model T
	Index *index.SpecIndex // index created from the document.
}

DocumentModel represents either a Swagger document (version 2) or an OpenAPI document (version 3) that is built from a parent Document.