Documentation
¶
Overview ¶
Package pathutil provides reference building, escaping, and path sanitization utilities for OpenAPI document traversal.
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)
Reference Token Escaping ¶
Component names are not always safe to drop into a JSON Pointer as-is: RFC 6901 gives "~" and "/" special meaning, so a component legitimately named "pet/summary" must be referenced as "#/definitions/pet~1summary". EscapeRefToken and UnescapeRefToken convert a single pointer token in each direction:
tok := pathutil.EscapeRefToken("pet/summary") // "pet~1summary"
name := pathutil.UnescapeRefToken("pet~1summary") // "pet/summary"
Escape per token, never across a whole reference — escaping the full string would rewrite the "/" separators that give the pointer its structure.
Output Path Sanitization ¶
SanitizeOutputPath validates and cleans output file paths for security. It rejects directory traversal ("..") and symlinks:
safe, err := pathutil.SanitizeOutputPath(userProvidedPath)
if err != nil {
return err // path traversal or symlink detected
}
Index ¶
- Constants
- Variables
- func CallbackRef(name string) string
- func DefinitionRef(name string) string
- func EscapeRefToken(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 RequestBodyRef(name string) string
- func ResponseRef(name string, oas2 bool) string
- func SanitizeOutputPath(path string) (string, error)
- func SchemaRef(name string) string
- func SecuritySchemeRef(name string, oas2 bool) string
- func UnescapeRefToken(token string) string
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 EscapeRefToken ¶ added in v1.54.0
EscapeRefToken escapes a component name for use as a single JSON Pointer token, per RFC 6901: "~" becomes "~0" and "/" becomes "~1".
Order matters — "~" must be escaped first, or the "~" introduced by escaping "/" would itself be escaped and produce "~01".
OAS 2.0 places no charset constraint on the keys of the root-level parameters, definitions, and responses objects, so a name containing either character is legitimate and must be escaped for a document to reference it. Building a reference by raw concatenation instead produces a pointer that names a different location and therefore never matches.
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 SanitizeOutputPath ¶ added in v1.52.0
SanitizeOutputPath validates and cleans an output file path. It resolves ".." components via filepath.Clean + filepath.Abs and rejects paths that resolve to symlinks. New files in existing directories are accepted. Returns the cleaned absolute path.
func SecuritySchemeRef ¶
SecuritySchemeRef builds the appropriate security scheme ref. If oas2 is true, returns "#/securityDefinitions/{name}", otherwise "#/components/securitySchemes/{name}".
func UnescapeRefToken ¶ added in v1.54.0
UnescapeRefToken reverses EscapeRefToken, recovering a component name from a single JSON Pointer token.
Use it anywhere a reference is split back into a name — renaming, pruning, or resolving a ref to its definition — or names containing "/" or "~" are corrupted. Order is the inverse of escaping: "~1" must be unescaped before "~0", or the "~" recovered from "~0" could combine with a following "1".
Mirrors unescapeJSONPointer in the parser's resolver, which has always implemented this for reference resolution.
Types ¶
This section is empty.
Source Files