Transform and master your API specs with ease.

Package openapi provides a suite of tools for working with OpenAPI specifications, making it easier to parse, format, manipulate, and generate code from these specs.

Whether you're looking to clean up existing API documentation or integrate API design into your development pipeline, this package is built to streamline your workflow.

This package is currently being utilized to format OpenAPI specifications in the go-api-libs project.

Introduction

The primary goals of this package are:

• Parsing OpenAPI specifications into a structured format.
• Formatting the parsed specifications, including sorting maps and merging duplicate content.
• Adding information programmatically to the specifications.
• Marshalling the modified specifications back into their original format.
• Utilizing the parsed specification for code generation.

This module is deliberately kept focused on representing and validating a specification. Transformations that not everyone needs — flattening, deduplicating, enriching, generating code — live in separate modules so that users who only want to parse, validate, and prettify a spec don't pay for them.

Features

• Comprehensive parsing of OpenAPI specifications.
• Flexible formatting options to improve readability and consistency.
• Ability to merge and deduplicate content within specifications.
• Programmatic modification of specifications before marshalling.
• Code generation capabilities based on parsed specifications.

Usage

package main

import (
    "fmt"

    "github.com/MarkRosemaker/openapi"
)

func main() {
    doc, err := openapi.LoadFromFile("path/to/openapi.json") // or openapi.yaml
    if err != nil {
        fmt.Println("Error parsing spec:", err)
        return
    }

    if err := doc.Validate(); err != nil {
        fmt.Println("Error validating spec:", err)
        return
    }

    // sort keys of each component in alphabetical order
    doc.Components.SortMaps()

	// write an improved version of your spec
    if err := doc.WriteToFile("path/to/openapi.json"); err != nil {
        fmt.Println("Error writing to file:", err)
        return
    }
}

The openapi family

This module is the foundation of a family of composable tools. Together they document an API that is not properly documented and then make it easy to use: record its traffic, get a specification that says what it actually does, and generate a Go library to call it with. Every tool operates on the *openapi.Document defined here, so they can also be combined freely.

The table lists them in dependency order: each builds only on those above it.

Module	Purpose	Builds on
openapi (this module)	Parse, validate, and write OpenAPI 3.x specifications
openapi-edit	Safe structural edits, such as renaming a schema and rewriting every $ref to it	openapi
openapi-compare	Compare specification objects — exact equality and shape equivalence	openapi
openapi-merge	Merge schemas that were inferred independently from different samples	openapi
openapi-enrich	Infer specification content from observed HTTP traffic	openapi, edit, merge
openapi-flatten	Promote inline definitions into named components entries	openapi
openapi-compress	Deduplicate and merge equivalent component schemas	openapi, compare, edit, enrich, merge
openapi-codegen	Generate Go types, clients, and servers from a specification	openapi, compare, edit, enrich, flatten, compress

The last four form the pipeline, in that order: openapi-enrich records traffic into a specification, openapi-flatten and openapi-compress normalize its structure, and openapi-codegen generates the library. Where that library fails to decode a response, recording the call and enriching again closes the gap.

Additional Information

• Go Reference: API documentation.
• Architecture: how the parts fit together.
• Roadmap: what is planned and not yet done.

Contributing

Contributions are welcome — please open an issue or a pull request on GitHub.

License

This project is licensed under the Apache 2.0 License.