Documentation
¶
Overview ¶
Package pathutil provides efficient path building utilities for OpenAPI document traversal.
The primary type is PathBuilder, which uses push/pop semantics to build paths incrementally without allocating intermediate strings. This is particularly useful in recursive traversal where paths are built on each recursive call but only used when reporting errors or differences.
PathBuilder Usage ¶
Use Get to obtain a pooled PathBuilder, and Put to return it:
path := pathutil.Get()
defer pathutil.Put(path)
path.Push("properties")
path.Push(propName)
// ... recurse ...
path.Pop()
path.Pop()
// Only call String() when needed (e.g., reporting an error)
if hasError {
return fmt.Errorf("error at %s", path.String())
}
Array indices are supported via PathBuilder.PushIndex:
path.Push("items")
path.PushIndex(0) // produces "items[0]"
Reference Builders ¶
The package also provides functions for building JSON Pointer references to OpenAPI components:
ref := pathutil.SchemaRef("Pet") // "#/components/schemas/Pet"
ref := pathutil.DefinitionRef("Pet") // "#/definitions/Pet"
These use simple string concatenation which Go optimizes well for two operands, avoiding the overhead of fmt.Sprintf.
Version-aware helpers handle OAS 2.0 vs 3.x differences:
ref := pathutil.ParameterRef("limit", true) // "#/parameters/limit" (OAS 2.0)
ref := pathutil.ParameterRef("limit", false) // "#/components/parameters/limit" (OAS 3.x)
Index ¶
- Constants
- Variables
- func CallbackRef(name string) string
- func DefinitionRef(name string) string
- func ExampleRef(name string) string
- func HeaderRef(name string) string
- func LinkRef(name string) string
- func ParameterRef(name string, oas2 bool) string
- func PathItemRef(name string) string
- func Put(p *PathBuilder)
- func RequestBodyRef(name string) string
- func ResponseRef(name string, oas2 bool) string
- func SchemaRef(name string) string
- func SecuritySchemeRef(name string, oas2 bool) string
- type PathBuilder
Constants ¶
const ( RefPrefixDefinitions = "#/definitions/" RefPrefixParameters = "#/parameters/" RefPrefixResponses = "#/responses/" RefPrefixSecurityDefinitions = "#/securityDefinitions/" )
OAS 2.0 reference prefixes
const ( RefPrefixSchemas = "#/components/schemas/" RefPrefixParameters3 = "#/components/parameters/" RefPrefixResponses3 = "#/components/responses/" RefPrefixExamples = "#/components/examples/" RefPrefixRequestBodies = "#/components/requestBodies/" RefPrefixHeaders = "#/components/headers/" RefPrefixSecuritySchemes = "#/components/securitySchemes/" RefPrefixLinks = "#/components/links/" RefPrefixCallbacks = "#/components/callbacks/" RefPrefixPathItems = "#/components/pathItems/" )
OAS 3.x reference prefixes
Variables ¶
var PathParamRegex = regexp.MustCompile(`\{([^}]+)\}`)
PathParamRegex matches path template parameters like {paramName}. It captures the parameter name inside the braces.
Functions ¶
func CallbackRef ¶
CallbackRef builds "#/components/callbacks/{name}" (OAS 3.x only).
func DefinitionRef ¶
DefinitionRef builds "#/definitions/{name}" (OAS 2.0).
func ExampleRef ¶
ExampleRef builds "#/components/examples/{name}" (OAS 3.x only).
func ParameterRef ¶
ParameterRef builds the appropriate parameter ref. If oas2 is true, returns "#/parameters/{name}", otherwise "#/components/parameters/{name}".
func PathItemRef ¶
PathItemRef builds "#/components/pathItems/{name}" (OAS 3.1+ only).
func RequestBodyRef ¶
RequestBodyRef builds "#/components/requestBodies/{name}" (OAS 3.x only).
func ResponseRef ¶
ResponseRef builds the appropriate response ref. If oas2 is true, returns "#/responses/{name}", otherwise "#/components/responses/{name}".
func SecuritySchemeRef ¶
SecuritySchemeRef builds the appropriate security scheme ref. If oas2 is true, returns "#/securityDefinitions/{name}", otherwise "#/components/securitySchemes/{name}".
Types ¶
type PathBuilder ¶
type PathBuilder struct {
// contains filtered or unexported fields
}
PathBuilder provides efficient incremental path construction. Uses push/pop semantics to avoid allocations during traversal. The full string is only materialized when String() is called.
func Get ¶
func Get() *PathBuilder
Get retrieves a PathBuilder from the pool, reset and ready to use.
func (*PathBuilder) Push ¶
func (p *PathBuilder) Push(segment string)
Push adds a segment to the path.
func (*PathBuilder) PushIndex ¶
func (p *PathBuilder) PushIndex(i int)
PushIndex adds an array index segment: "[0]", "[1]", etc.
func (*PathBuilder) String ¶
func (p *PathBuilder) String() string
String materializes the full path. Only call when the path is needed.
Source Files