Documentation
¶
Index ¶
- Variables
- func BundleBytes(bytes []byte, configuration *datamodel.DocumentConfiguration) ([]byte, error)
- func BundleBytesComposed(bytes []byte, configuration *datamodel.DocumentConfiguration, ...) ([]byte, error)
- func BundleBytesWithConfig(bytes []byte, configuration *datamodel.DocumentConfiguration, ...) ([]byte, error)
- func BundleDocument(model *v3.Document) ([]byte, error)
- func BundleDocumentComposed(model *v3.Document, compositionConfig *BundleCompositionConfig) ([]byte, error)
- func BundleDocumentWithConfig(model *v3.Document, bundleConfig *BundleInlineConfig) ([]byte, error)
- func DetectOpenAPIComponentType(node *yaml.Node) (string, bool)
- type BundleCompositionConfig
- type BundleInlineConfig
- type BundleResult
- type ComponentOrigin
- type ComponentOriginMap
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidModel = errors.New("invalid model")
ErrInvalidModel is returned when the model is not usable.
Functions ¶
func BundleBytes ¶
func BundleBytes(bytes []byte, configuration *datamodel.DocumentConfiguration) ([]byte, error)
BundleBytes will take a byte slice of an OpenAPI specification and return a bundled version of it. This is useful for when you want to take a specification with external references, and you want to bundle it into a single document.
This function will 'resolve' all references in the specification and return a single document. The resulting document will be a valid OpenAPI specification, containing no references.
Circular references will not be resolved and will be skipped.
func BundleBytesComposed ¶ added in v0.22.0
func BundleBytesComposed(bytes []byte, configuration *datamodel.DocumentConfiguration, compositionConfig *BundleCompositionConfig) ([]byte, error)
BundleBytesComposed will take a byte slice of an OpenAPI specification and return a composed bundled version of it. this is the same as BundleBytes, but it will compose the bundling instead of inline it.
Composed means that every external file will have references lifted out and added to the `components` section of the document. Names will be preserved where possible, conflicts will dealt with by using a delimiter and appending a number.
func BundleBytesWithConfig ¶ added in v0.30.0
func BundleBytesWithConfig(bytes []byte, configuration *datamodel.DocumentConfiguration, bundleConfig *BundleInlineConfig) ([]byte, error)
BundleBytesWithConfig will take a byte slice of an OpenAPI specification and return a bundled version of it, with additional configuration options for inline bundling behavior.
Use the BundleInlineConfig to enable features like ResolveDiscriminatorExternalRefs which copies external schemas referenced by discriminator mappings to the root document's components section.
func BundleDocument ¶
BundleDocument will take a v3.Document and return a bundled version of it. This is useful for when you want to take a document that has been built from a specification with external references, and you want to bundle it into a single document.
This function will 'resolve' all references in the specification and return a single document. The resulting document will be a valid OpenAPI specification, containing no references.
Circular references will not be resolved and will be skipped.
func BundleDocumentComposed ¶ added in v0.22.0
func BundleDocumentComposed(model *v3.Document, compositionConfig *BundleCompositionConfig) ([]byte, error)
BundleDocumentComposed will take a v3.Document and return a composed bundled version of it. Composed means that every external file will have references lifted out and added to the `components` section of the document. Names will be preserved where possible, conflicts will be appended with a number. If the type of the reference cannot be determined, it will be added to the `components` section as a `Schema` type, a warning will be logged. The document model will be mutated permanently.
Circular references will not be resolved and will be skipped.
func BundleDocumentWithConfig ¶ added in v0.30.0
func BundleDocumentWithConfig(model *v3.Document, bundleConfig *BundleInlineConfig) ([]byte, error)
BundleDocumentWithConfig will take a v3.Document and return a bundled version of it, with additional configuration options for inline bundling behavior.
Use the BundleInlineConfig to enable features like ResolveDiscriminatorExternalRefs which copies external schemas referenced by discriminator mappings to the root document's components section.
func DetectOpenAPIComponentType ¶ added in v0.22.0
DetectOpenAPIComponentType attempts to determine what type of OpenAPI component a node represents. It returns the component type as a string (schema, response, parameter, etc.) and a boolean indicating whether the type was successfully detected.
Types ¶
type BundleCompositionConfig ¶ added in v0.22.0
type BundleCompositionConfig struct {
Delimiter string // Delimiter is used to separate clashing names. Defaults to `__`.
StrictValidation bool // StrictValidation will cause bundling to fail on invalid OpenAPI specs (e.g. $ref with siblings)
}
BundleCompositionConfig is used to configure the composition of OpenAPI documents when using BundleDocumentComposed.
type BundleInlineConfig ¶ added in v0.30.0
type BundleInlineConfig struct {
// ResolveDiscriminatorExternalRefs when true, copies external schemas referenced
// by discriminator mappings to the root document's components section.
// This ensures the bundled output is valid and self-contained when discriminators
// in external files reference other schemas in those external files.
// Default: false (preserves existing behavior of keeping external refs as-is)
ResolveDiscriminatorExternalRefs bool
// InlineLocalRefs controls whether local component references are inlined during bundling.
// When nil, falls back to DocumentConfiguration.BundleInlineRefs.
// - false: preserve local refs like #/components/schemas/Pet (discriminator-safe, default behavior)
// - true: inline all refs including local component refs
// Default: nil (uses DocumentConfiguration.BundleInlineRefs)
InlineLocalRefs *bool
}
BundleInlineConfig provides configuration options for inline bundling.
Example usage:
// Inline everything including local refs
inlineTrue := true
config := &BundleInlineConfig{
InlineLocalRefs: &inlineTrue,
}
bundled, err := BundleBytesWithConfig(specBytes, docConfig, config)
type BundleResult ¶ added in v0.33.1
type BundleResult struct {
// Bytes is the bundled YAML output.
Bytes []byte
// Origins maps bundled JSON Pointer paths to their original locations.
// This enables navigation from bundled components back to source files.
Origins ComponentOriginMap
}
BundleResult contains the bundled bytes and origin tracking information.
func BundleBytesComposedWithOrigins ¶ added in v0.33.1
func BundleBytesComposedWithOrigins(bytes []byte, configuration *datamodel.DocumentConfiguration, compositionConfig *BundleCompositionConfig) (*BundleResult, error)
BundleBytesComposedWithOrigins returns a bundled spec with origin tracking for navigation. This enables consumers to map bundled components back to their original file locations.
func BundleDocumentComposedWithOrigins ¶ added in v0.33.1
func BundleDocumentComposedWithOrigins(model *v3.Document, compositionConfig *BundleCompositionConfig) (*BundleResult, error)
BundleDocumentComposedWithOrigins will take a v3.Document and return a composed bundled version of it along with origin tracking information. This allows consumers to map bundled components back to their original file locations. The document model will be mutated permanently.
Circular references will not be resolved and will be skipped.
func NewBundleResult ¶ added in v0.33.1
func NewBundleResult() *BundleResult
NewBundleResult creates a new BundleResult with initialized maps.
func (*BundleResult) AddOrigin ¶ added in v0.33.1
func (r *BundleResult) AddOrigin(bundledRef string, origin *ComponentOrigin)
AddOrigin adds a component origin to the result.
func (*BundleResult) GetOrigin ¶ added in v0.33.1
func (r *BundleResult) GetOrigin(bundledRef string) *ComponentOrigin
GetOrigin retrieves the origin for a bundled reference.
func (*BundleResult) OriginCount ¶ added in v0.33.1
func (r *BundleResult) OriginCount() int
OriginCount returns the number of tracked origins.
type ComponentOrigin ¶ added in v0.33.1
type ComponentOrigin struct {
// OriginalFile is the absolute path to the file containing the original definition.
// e.g., "/path/to/models/User.yaml"
OriginalFile string `json:"originalFile" yaml:"originalFile"`
// OriginalRef is the JSON Pointer within the original file.
// e.g., "#/components/schemas/User" or "#/User"
OriginalRef string `json:"originalRef" yaml:"originalRef"`
// OriginalName is the component name before any collision renaming.
// e.g., "User" (even if bundled as "User__2")
OriginalName string `json:"originalName" yaml:"originalName"`
// Line is the 1-based line number in the original file.
Line int `json:"line" yaml:"line"`
// Column is the 1-based column number in the original file.
Column int `json:"column" yaml:"column"`
// WasRenamed indicates if the component was renamed due to collision.
WasRenamed bool `json:"wasRenamed" yaml:"wasRenamed"`
// BundledRef is the final JSON Pointer in the bundled document.
// e.g., "#/components/schemas/User__2"
BundledRef string `json:"bundledRef" yaml:"bundledRef"`
// ComponentType is the type of component (schemas, responses, parameters, etc.)
ComponentType string `json:"componentType" yaml:"componentType"`
}
ComponentOrigin tracks the original location of a component that was lifted into the bundled document's components section.
type ComponentOriginMap ¶ added in v0.33.1
type ComponentOriginMap map[string]*ComponentOrigin
ComponentOriginMap maps bundled refs to their original locations. Key is the bundled JSON Pointer (e.g., "#/components/schemas/User").
Source Files
Directories