-
Notifications
You must be signed in to change notification settings - Fork 4
Expand file tree
/
Copy pathdoc.go
More file actions
146 lines (146 loc) · 5.14 KB
/
Copy pathdoc.go
File metadata and controls
146 lines (146 loc) · 5.14 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
// Package overlay provides support for OpenAPI Overlay Specification v1.0.0.
//
// The OpenAPI Overlay Specification provides a standardized mechanism for augmenting
// OpenAPI documents through targeted transformations. Overlays use JSONPath expressions
// to select specific locations in an OpenAPI document and apply updates or removals.
//
// # Quick Start
//
// Apply an overlay using functional options (recommended):
//
// result, err := overlay.ApplyWithOptions(
// overlay.WithSpecFilePath("openapi.yaml"),
// overlay.WithOverlayFilePath("changes.yaml"),
// )
// if err != nil {
// log.Fatal(err)
// }
// fmt.Printf("Applied %d changes\n", result.ActionsApplied)
//
// Or use a reusable Applier instance:
//
// a := overlay.NewApplier()
// a.StrictTargets = true
// result, err := a.Apply("openapi.yaml", "changes.yaml")
//
// # Overlay Document Structure
//
// An overlay document contains:
// - overlay: The specification version (must be "1.0.0")
// - info: Metadata with title and version
// - extends: Optional URI of the target document
// - actions: Ordered list of transformation actions
//
// Example overlay document:
//
// overlay: 1.0.0
// info:
// title: Production Customizations
// version: 1.0.0
// actions:
// - target: $.info
// update:
// title: Production API
// x-environment: production
// - target: $.paths[[email protected]==true]
// remove: true
//
// # Action Types
//
// Update actions merge content into matched nodes:
// - For objects: Properties are recursively merged
// - For arrays: The update value is appended
// - Same-name properties are replaced, new properties are added
//
// Remove actions delete matched nodes from their parent container.
// When both update and remove are specified, remove takes precedence.
//
// # JSONPath Support
//
// This package includes a built-in JSONPath implementation supporting:
// - Basic navigation: $.info, $.paths['/users']
// - Wildcards: $.paths.*, $.paths.*.*
// - Array indices: $.servers[0], $.servers[-1]
// - Simple filters: $.paths[[email protected]==true]
// - Compound filters: $.paths[[email protected]==true && @.x-internal==false]
// - Recursive descent: $..description (find all descriptions at any depth)
//
// # Dry-Run Preview
//
// Preview overlay changes without modifying the document:
//
// result, _ := overlay.DryRunWithOptions(
// overlay.WithSpecFilePath("openapi.yaml"),
// overlay.WithOverlayFilePath("changes.yaml"),
// )
// for _, change := range result.Changes {
// fmt.Printf("Would %s %d nodes at %s\n",
// change.Operation, change.MatchCount, change.Target)
// }
//
// # Validation
//
// Overlays can be validated before application:
//
// o, _ := overlay.ParseOverlayFile("changes.yaml")
// if errs := overlay.Validate(o); len(errs) > 0 {
// for _, err := range errs {
// fmt.Println(err)
// }
// }
//
// # Structured Warnings
//
// The overlay package provides structured warnings through the [ApplyWarning] type, which
// includes detailed context about non-fatal issues encountered during overlay application.
// Each warning has a category, action index, and target JSONPath for programmatic handling.
//
// Access structured warnings from the result:
//
// result, _ := overlay.ApplyWithOptions(
// overlay.WithSpecFilePath("openapi.yaml"),
// overlay.WithOverlayFilePath("changes.yaml"),
// )
// for _, w := range result.StructuredWarnings {
// fmt.Printf("[%s] %s\n", w.Category, w.Message)
// if w.HasLocation() {
// fmt.Printf(" at %s\n", w.Location())
// }
// }
//
// Filter warnings by category:
//
// noMatches := result.StructuredWarnings.ByCategory(overlay.WarnNoMatch)
//
// Warning categories include:
// - WarnNoMatch: Action target matched no nodes in the document
// - WarnActionError: Error executing an action (with cause)
//
// For backward compatibility, warnings are also available as []string via result.Warnings.
//
// # Package Chaining with ToParseResult
//
// The overlay package supports chaining with other oastools packages through
// the [ApplyResult.ToParseResult] method. This enables workflows like:
//
// // Parse → Apply Overlay → Validate
// parsed, _ := parser.ParseWithOptions(parser.WithFilePath("openapi.yaml"))
// result, _ := overlay.ApplyWithOptions(
// overlay.WithSpecParsed(*parsed),
// overlay.WithOverlayFilePath("changes.yaml"),
// )
// issues, _ := validator.ValidateWithOptions(validator.WithParsed(*result.ToParseResult()))
//
// Note that when the overlay is applied to a raw map[string]any document (rather than
// a typed *parser.OAS3Document or *parser.OAS2Document), the version information in
// the resulting ParseResult will be empty. For full version tracking, ensure the input
// document is a typed document obtained from parsing.
//
// # Related Packages
//
// The overlay package integrates with other oastools packages:
// - [github.com/erraggy/oastools/parser] - Parse OpenAPI specifications
// - [github.com/erraggy/oastools/validator] - Validate specifications
// - [github.com/erraggy/oastools/joiner] - Join multiple specifications
// - [github.com/erraggy/oastools/converter] - Convert between OAS versions
package overlay