OapiCodemode.Pointer (oapi_codemode v0.5.0)

Copy Markdown View Source

Same-document JSON pointer resolution ("#/components/schemas/Pet").

One home for the escaping rules and the walk, because three callers need the same answer: Ingest.Deref inlining refs, Ingest resolving the refs that decide which operations exist, and (later) a SpecStore's pointer/4 serving refs that are not stored components. A pointer that leaves the document or names a missing key is :error — the caller decides what marker that becomes.

The walk is maps only by default. Array indexing is real JSON pointer (RFC 6901) but no ref in a well-formed OpenAPI document needs it, so it is opt-in per call: resolve(doc, pointer, arrays: true). Every caller that predates the option keeps the maps-only walk, which is byte-for-byte the 0.4.0 behaviour — a spec that pointed into an array used to be :error and still is, unless the caller asks otherwise.

Summary

Functions

escape(token)

Escapes one pointer token, for building a pointer to a known location.

resolve(root, pointer, opts \\ [])
unescape(token)

Unescapes one pointer token, for reading a name back out of a pointer.

Functions

escape(token)

@spec escape(String.t()) :: String.t()

Escapes one pointer token, for building a pointer to a known location.

resolve(root, pointer, opts \\ [])

@spec resolve(term(), String.t(), keyword()) :: {:ok, term()} | :error

unescape(token)

@spec unescape(String.t()) :: String.t()

Unescapes one pointer token, for reading a name back out of a pointer.

The inverse of escape/1, public for the same reason: OapiCodemode.Resolve has to decide whether "#/components/schemas/Foo~1Bar" names the stored component "Foo/Bar", and a second copy of the escaping rules is exactly what this module exists to prevent.