Overview

The openapi package provides Go types that directly represent the OpenAPI 3.1 specification. Rather than wrapping the specification in builders or validation layers, this package treats the spec as data—struct fields map to spec fields, and standard marshalling handles serialization.

Design Philosophy

Types as Specification

Every OpenAPI construct has a corresponding Go type. The OpenAPI struct contains Info, Paths, and Components fields because the specification defines those fields. Field names match the spec (with Go naming conventions), and struct tags handle the JSON/YAML field name mapping.

This direct mapping means:

• Reading the OpenAPI 3.1 specification teaches you the package
• No translation layer between what you write and what gets serialized
• IDE autocompletion guides you through the spec structure

Zero Abstraction

The package provides no builders, no fluent APIs, no validation methods. You construct specs using Go's native struct literal syntax:

spec := &openapi.OpenAPI{
    OpenAPI: "3.1.0",
    Info: openapi.Info{Title: "My API", Version: "1.0.0"},
}

This is intentional. Abstractions would hide the specification's structure and create a learning curve separate from the spec itself. The spec is the API.

Minimal Dependencies

The package depends only on gopkg.in/yaml.v3 for YAML support. JSON marshalling uses the standard library. No validation libraries, no reflection utilities—just data structures.

Scope

This package handles:

• Type definitions: All OpenAPI 3.1 objects as Go structs
• Serialization: JSON and YAML marshalling/unmarshalling
• Schema types: The SchemaType helper for JSON Schema's type field (which can be a string or array)

This package does not handle:

• Validation: Checking that a spec is semantically correct
• Reference resolution: Dereferencing $ref pointers
• Code generation: Producing server/client code from specs
• HTTP routing: Matching requests to operations

These concerns belong in separate packages that can depend on these types.

Versioning

This package targets OpenAPI 3.1, which aligns with JSON Schema 2020-12. The key differences from OpenAPI 3.0:

• Schema type can be an array (e.g., ["string", "null"])
• nullable is replaced by including "null" in the type array
• Webhooks are a top-level construct
• JSON Schema keywords like const are available

The SchemaType type handles the string-or-array complexity transparently.