Documentation
¶
Overview ¶
Package load provides functions to load OpenAPI specifications from various sources.
Overview ¶
The load package handles loading OpenAPI specs from files, URLs, stdin, and glob patterns. It automatically resolves $ref references and extracts version information from the spec.
Usage ¶
Load a spec from a file, URL, or stdin:
source, _ := load.NewSource("openapi.yaml")
specInfo, err := load.NewSpecInfo(openapi3.NewLoader(), source)
Load multiple specs using glob patterns:
specInfos, err := load.NewSpecInfoFromGlob(openapi3.NewLoader(), "specs/*.yaml")
Preprocessing Options ¶
Options can preprocess specs after loading to improve diff accuracy:
specInfo, err := load.NewSpecInfo(loader, source,
load.WithFlattenAllOf(), // Merge allOf schemas into single schema
load.WithFlattenParams(), // Move common path parameters to operations
load.WithLowercaseHeaders(), // Normalize header names to lowercase
)
These options use the flatten subpackages:
- flatten/allof: merges allOf schemas for more accurate breaking change detection
- flatten/commonparams: moves path-level parameters to operations for consistent comparison
- flatten/headers: lowercases header names since HTTP headers are case-insensitive
SpecInfo ¶
SpecInfo wraps a loaded spec with metadata:
- Spec: the parsed openapi3.T object with resolved references
- Url: the source path/URL the spec was loaded from
- Version: the API version extracted from info.version
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
Option functions can be used to preprocess specs after loading them
func WithFlattenAllOf ¶
func WithFlattenAllOf() Option
WithFlattenAllOf returns SpecInfos with flattened allOf
func WithFlattenParams ¶
func WithFlattenParams() Option
WithFlattenParams returns SpecInfos with Common Parameters combined into operation parameters See here for Common Parameters definition: https://swagger.io/docs/specification/describing-parameters/
func WithLowercaseHeaders ¶
func WithLowercaseHeaders() Option
WithLowercaseHeaders returns SpecInfos with header names converted to lowercase
type Source ¶
type Source struct {
Path string
Uri *url.URL
Type SourceType
}
func NewSource ¶
NewSource creates a Source by categorizing the input path as stdin, URL, git revision, or file. This function is intentionally infallible (does not return an error) to allow clean usage in struct literal initialization and avoid error handling boilerplate in hundreds of call sites throughout the codebase.
Categorization rules (evaluated in order):
- "-" → SourceTypeStdin
- Git revision syntax (e.g. "HEAD:openapi.yaml", "origin/main:api/openapi.yaml") → SourceTypeGitRevision
- Valid http/https URLs → SourceTypeURL
- Everything else (including URLs with unsupported schemes) → SourceTypeFile
Git revision syntax is "<ref>:<path>" where <ref> is any git ref (branch, tag, commit SHA, or expressions like HEAD~1) and <path> is the file path within the repo. Multi-file specs with relative $refs are fully supported — referenced files are also read via "git show".
Actual validation and error handling occurs later when the source is loaded, providing clean separation of concerns between categorization and I/O.
func (*Source) DisplayPath ¶ added in v1.12.0
DisplayPath returns the path suitable for display and source-location reporting. For git revisions it strips the ref prefix (e.g. "origin/main:openapi.yaml" → "openapi.yaml").
func (*Source) IsGitRevision ¶ added in v1.11.11
type SourceType ¶
type SourceType int
const ( SourceTypeStdin SourceType = iota SourceTypeURL SourceTypeFile SourceTypeGitRevision )
type SpecInfo ¶
SpecInfo contains information about an OpenAPI spec and its metadata
func NewSpecInfo ¶
NewSpecInfo creates a SpecInfo from a local file path, a URL, or stdin
func NewSpecInfoFromGlob ¶
func NewSpecInfoFromGlob(loader *openapi3.Loader, glob string, options ...Option) ([]*SpecInfo, error)
NewSpecInfoFromGlob creates SpecInfos from local files matching the specified glob parameter
func (*SpecInfo) GetVersion ¶
type SpecInfoPair ¶
func NewSpecInfoPair ¶
func NewSpecInfoPair(specInfo1, specInfo2 *SpecInfo) *SpecInfoPair
func (*SpecInfoPair) GetBaseVersion ¶
func (specInfoPair *SpecInfoPair) GetBaseVersion() string
func (*SpecInfoPair) GetRevisionVersion ¶
func (specInfoPair *SpecInfoPair) GetRevisionVersion() string
Source Files