A growing implementation of the OpenAPI Specification. More...
Typedefs | |
| using | sourcemeta::core::OpenAPIDependencyCallback |
| using | sourcemeta::core::OpenAPIResolverResult = OwnedOrReference<JSON> |
| using | sourcemeta::core::OpenAPIResolver = std::function<OpenAPIResolverResult(std::string_view)> |
Enumerations | |
| enum class | sourcemeta::core::OpenAPIVersion : std::uint8_t { OpenAPIVersion::OPENAPI_3_0 , OpenAPIVersion::OPENAPI_3_1 , OpenAPIVersion::OPENAPI_3_2 } |
Functions | |
| SOURCEMETA_CORE_OPENAPI_EXPORT auto | sourcemeta::core::openapi_version (const JSON &document) -> std::optional< OpenAPIVersion > |
| SOURCEMETA_CORE_OPENAPI_EXPORT auto | sourcemeta::core::openapi_version_name (const OpenAPIVersion version) noexcept -> JSON::StringView |
| SOURCEMETA_CORE_OPENAPI_EXPORT auto | sourcemeta::core::openapi_version_string (const JSON &document) -> std::optional< JSON::StringView > |
| SOURCEMETA_CORE_OPENAPI_EXPORT auto | sourcemeta::core::openapi_is_document (const JSON &document) -> bool |
| SOURCEMETA_CORE_OPENAPI_EXPORT auto | sourcemeta::core::openapi_base (const JSON &document, const std::string_view retrieval) -> JSON::String |
| SOURCEMETA_CORE_OPENAPI_EXPORT auto | sourcemeta::core::openapi_format (JSON &document, const OpenAPIFrame &frame) -> void |
| SOURCEMETA_CORE_OPENAPI_EXPORT auto | sourcemeta::core::openapi_bundle (JSON &document, const SchemaWalker &walker, const SchemaResolver &schema_resolver, const OpenAPIResolver &resolver, const OpenAPIBundleOptions &options={}) -> void |
| SOURCEMETA_CORE_OPENAPI_EXPORT auto | sourcemeta::core::openapi_bundle (const JSON &document, const SchemaWalker &walker, const SchemaResolver &schema_resolver, const OpenAPIResolver &resolver, const OpenAPIBundleOptions &options={}) -> JSON |
| SOURCEMETA_CORE_OPENAPI_EXPORT auto | sourcemeta::core::openapi_dependencies (const JSON &document, const SchemaWalker &walker, const SchemaResolver &schema_resolver, const OpenAPIResolver &resolver, const OpenAPIDependencyCallback &callback, const OpenAPIDependencyOptions &options={}) -> std::uint64_t |
| SOURCEMETA_CORE_OPENAPI_EXPORT auto | sourcemeta::core::openapi_kind_name (const OpenAPIObjectKind kind) noexcept -> JSON::StringView |
| SOURCEMETA_CORE_OPENAPI_EXPORT auto | sourcemeta::core::openapi_operation_kind_name (const OpenAPIOperationKind kind) noexcept -> JSON::StringView |
A growing implementation of the OpenAPI Specification.
This module reports where an OpenAPI Description declares its JSON Schemas and leaves what is inside them to a JSON Schema implementation.
This functionality is included as follows:
| struct sourcemeta::core::OpenAPIContact |
The contact information that an OpenAPI Description declares for the API. Every value borrows from the document it was read from, so that document must outlive this
Public Attributes | |
|---|---|
| std::optional< JSON::StringView > | name {std::nullopt} |
| The identifying name of the contact person or organisation. | |
| std::optional< JSON::StringView > | url {std::nullopt} |
| Where to find the contact information, as a URI reference. | |
| std::optional< JSON::StringView > | email {std::nullopt} |
| The email address of the contact person or organisation. | |
| struct sourcemeta::core::OpenAPILicense |
The license information that an OpenAPI Description declares for the API. Every value borrows from the document it was read from, so that document must outlive this
Public Attributes | |
|---|---|
| JSON::StringView | name {} |
| The license name used for the API. | |
| std::optional< JSON::StringView > | identifier {std::nullopt} |
| std::optional< JSON::StringView > | url {std::nullopt} |
| Where to find the license used for the API, as a URI reference. | |
| std::optional<JSON::StringView> sourcemeta::core::OpenAPILicense::identifier {std::nullopt} |
The SPDX license expression for the API, recorded as it was written, as the specification states no requirement on its syntax
| struct sourcemeta::core::OpenAPIInfo |
The metadata that an OpenAPI Description declares about the API it describes. Every value borrows from the document it was read from, so that document must outlive this
Public Attributes | |
|---|---|
| JSON::StringView | title {} |
| The title of the API. | |
| JSON::StringView | version {} |
| std::optional< JSON::StringView > | summary {std::nullopt} |
| A short summary of the API. | |
| std::optional< JSON::StringView > | description {std::nullopt} |
| A description of the API, which may be written in CommonMark. | |
| std::optional< JSON::StringView > | terms_of_service {std::nullopt} |
| Where to find the terms of service for the API, as a URI reference. | |
| std::optional< OpenAPIContact > | contact {std::nullopt} |
| The contact information for the API. | |
| std::optional< OpenAPILicense > | license {std::nullopt} |
| The license information for the API. | |
| JSON::StringView sourcemeta::core::OpenAPIInfo::version {} |
The version of the document, which is unrelated to the version of the OpenAPI Specification that it declares
| class sourcemeta::core::OpenAPIFrame |
A static analysis pass over an OpenAPI Description that computes the locations it exposes, the references between them, the operations it describes, and where its JSON Schemas begin. It does not look inside those schemas. For example:
A frame is analysed once, on construction, and what it reports never changes afterwards. Reading one is not thread safe even so, as it answers out of caches it fills as it goes. A frame cannot be copied or moved, so it is built where it is read.
Public Types | |
|---|---|
| using | ObjectKind = OpenAPIObjectKind |
| What kind of Object a position holds. | |
| using | OperationKind = OpenAPIOperationKind |
| How an Operation Object is reached from the entry document. | |
| using | Locations = std::map<JSON::String, Location, std::less<>> |
| using | References = std::map<JSON::String, Reference, std::less<>> |
Public Member Functions | |
| OpenAPIFrame (const JSON &document, const SchemaWalker &walker, const SchemaResolver &resolver, const std::string_view default_base="", std::uint64_t max_locations=std::numeric_limits< std::uint64_t >::max(), const OpenAPIFrame *entry=nullptr) | |
| OpenAPIFrame (const OpenAPIFrame &)=delete | |
| OpenAPIFrame (OpenAPIFrame &&)=delete | |
| auto | version () const noexcept -> OpenAPIVersion |
| auto | info () const noexcept -> const OpenAPIInfo & |
| auto | base () const noexcept -> JSON::StringView |
| auto | standalone () const noexcept -> bool |
| auto | schemas () const noexcept -> const SchemaFrame & |
| auto | locations () const noexcept -> const Locations & |
| Every Object the description holds, keyed by the URI addressing each one. | |
| auto | references () const noexcept -> const References & |
| auto | security_references () const noexcept -> const References & |
| auto | operations () const noexcept -> const std::vector< Operation > & |
| Every operation the described API exposes. | |
| auto | discriminators () const noexcept -> const std::vector< Discriminator > & |
| template<std::invocable< const JSON::String &, const Location & > F> | |
| auto | for_each_object (const F &callback) const -> void |
| template<std::predicate< const JSON::String &, const Location & > F> | |
| auto | any_object (const F &predicate) const -> bool |
| template<std::invocable< const JSON::String &, const Reference & > F> | |
| auto | for_each_reference (const F &callback) const -> void |
| template<std::invocable< const JSON::String &, const Reference & > F> | |
| auto | for_each_security_reference (const F &callback) const -> void |
| template<std::invocable< const Operation & > F> | |
| auto | for_each_operation (const F &callback) const -> void |
| template<std::invocable< const Discriminator & > F> | |
| auto | for_each_discriminator (const F &callback) const -> void |
| auto | traverse (const JSON::StringView uri) const -> const Location * |
| auto | uri (const Pointer &pointer) const -> JSON::String |
| auto | object_count () const noexcept -> std::size_t |
| How many Objects the description holds. | |
| auto | reference_count () const noexcept -> std::size_t |
| auto | to_json (const std::optional< PointerPositionTracker > &tracker=std::nullopt) const -> JSON |
| using sourcemeta::core::OpenAPIFrame::Locations = std::map<JSON::String, Location, std::less<>> |
| using sourcemeta::core::OpenAPIFrame::References = std::map<JSON::String, Reference, std::less<>> |
The references a frame holds, keyed by the URI of the Object that makes each one
| sourcemeta::core::OpenAPIFrame::OpenAPIFrame | ( | const JSON & | document, |
| const SchemaWalker & | walker, | ||
| const SchemaResolver & | resolver, | ||
| const std::string_view | default_base = "", | ||
| std::uint64_t | max_locations = std::numeric_limits< std::uint64_t >::max(), | ||
| const OpenAPIFrame * | entry = nullptr ) |
Frame an OpenAPI Description from a given document. That document must outlive the frame, as the metadata it reports borrows from it. The given base need not, as the frame canonicalises it into a string of its own
The base is the retrieval URI of the document. OpenAPI 3.1 offers a document no way of declaring an identity of its own, so under that revision this is the only way to give the description one. From 3.2 onwards a document may declare $self, which takes precedence once it is absolute, resolving against this when relative and standing aside when neither gives it a scheme
Only the given document is read. A reference that leaves it is recorded and left there, and a frame holding one of those does not stand alone
The walker and the resolver are what reading inside a Schema Object takes, as a Schema Object is JSON Schema's to make sense of rather than this specification's. Neither is defaulted, as which dialects a description may be written against is the caller's to state: pass sourcemeta::core::schema_walker and sourcemeta::core::schema_resolver for the dialects that are published, and a resolver of your own for one that is not. The frame keeps the resolver and asks it again when exporting, so whatever it reaches for has to be there for as long as the frame is
The places the description holds and the places its Schema Objects hold are places of the one description, so they spend from the one allowance. Bound it to throw sourcemeta::core::OpenAPIFrameLimitError rather than register past it, which reports the allowance the caller set rather than whatever was left of it
A base that establishes nothing is given as the empty URI reference, which leaves the document to name itself and leaves every relative reference it makes relative where it names nothing absolute either. Anything else must carry a scheme, and one that does not is refused before the document is read, which is why such a refusal names no place within it
A document that does not conform to the specification is rejected here rather than reported back, by throwing sourcemeta::core::OpenAPIError. What sits inside a Schema Object is held to JSON Schema instead, so one naming a dialect nothing resolves throws sourcemeta::core::SchemaResolutionError, one declaring an identifier or a reference that is no URI throws sourcemeta::core::SchemaKeywordError, and two colliding on an identifier or on an anchor throw sourcemeta::core::SchemaFrameError and sourcemeta::core::SchemaAnchorCollisionError respectively. One whose dialect or base dialect cannot be settled at all throws sourcemeta::core::SchemaUnknownDialectError or sourcemeta::core::SchemaUnknownBaseDialectError
A document that is not the one a description begins at resolves the component and tag names it uses from the document that is, which is what the entry frame is for. Pass the frame of that document to read this one as part of the same description, and nothing to read it on its own
|
inlinenodiscard |
Check whether any Object the description holds satisfies the predicate. For example:
|
nodiscardnoexcept |
Get the base URI that relative references in the entry document resolve against, canonicalised, or the empty URI reference when nothing established one, which leaves those references relative. It is the $self the entry document declares, and the retrieval URI the caller supplied when it declares none or when what it declares cannot be made absolute, in either case stripped of any fragment. For example:
|
nodiscardnoexcept |
Every URI a Discriminator Object names, which is a reference the schemas hold rather than one the shell around them does
|
inline |
Iterate over every URI a Discriminator Object names. For example:
|
inline |
Iterate over every Object the description holds, along with the URI the frame keys it by. For example:
|
inline |
Iterate over every operation the described API exposes. For example:
|
inline |
Iterate over every reference the description makes, along with the URI of the Object that makes it. For example:
|
inline |
Iterate over every scheme a Security Requirement Object names by the URI of one, along with the URI of the Object that names it. For example:
|
nodiscardnoexcept |
Get the metadata that the entry document declares about the API. For example:
|
nodiscardnoexcept |
How many references the description makes, not counting what a Security Requirement Object names by the URI of a scheme
|
nodiscardnoexcept |
Every reference the description makes, keyed by the URI of the Object that makes it rather than by its $ref member, so that where a reference comes from is a location like any other
|
nodiscardnoexcept |
Get the frame of every Schema Object the description holds, which a schema location names its part of by key. For example:
|
nodiscardnoexcept |
Every scheme a Security Requirement Object names by the URI of one, which OpenAPI Specification 3.2.1 admits alongside the name of a component. These are kept apart from the references above because a single such Object may name several, while every other way of naming an Object is written down where the Object that makes it sits
|
nodiscardnoexcept |
Check whether everything this description references is inside what was framed, which counts what its Schema Objects reference as much as what the shell around them does. The dialect a Schema Object names is not one of those, as a schema is under no obligation to carry the meta-schema it is written against. For example:
|
nodiscard |
Export the frame as JSON. This is the complete state of the frame. It asks the resolver the frame kept, so a meta-schema that has gone out of reach since throws sourcemeta::core::SchemaResolutionError here rather than at construction.
Pass the tracker that read the document to report where every place the export names by a pointer sits within it, which counts the places its Schema Objects hold as much as the Objects around them. A place the tracker holds nothing for reports a null position, and where no tracker is given no position is reported at all. For example:
|
nodiscard |
The Object a URI names, or nothing when the frame holds none. This is what turns the destination of a reference into the Object it lands on, as every destination is one of the URIs this frame addresses its Objects by. For example:
|
nodiscard |
The URI this frame addresses the given position by, which is the inverse of traversal. For example:
|
nodiscardnoexcept |
Get the version of the OpenAPI Specification that the entry document declares. The patch component of that declaration carries no meaning, so every 3.1.x release reports the same version. For example:
| struct sourcemeta::core::OpenAPIBundleOptions |
Everything bundling takes beyond the document and how to reach the rest
Public Types | |
|---|---|
| using | Callback |
| using | Namer = std::function<JSON::String(JSON::StringView, JSON::StringView)> |
Public Attributes | |
| std::string_view | default_base {} |
| std::uint64_t | max_locations {std::numeric_limits<std::uint64_t>::max()} |
| Callback | callback {} |
| A callback to report each place that bundling embedded. | |
| Namer | namer {} |
| A callback to name each place that bundling embeds. | |
A callback to report what bundling embedded, as the URI of the place it came from and a pointer from the root of the document it landed at. Bundling renames what it embeds to hold up as a component name, so this is the only way to know which place became which component
| using sourcemeta::core::OpenAPIBundleOptions::Namer = std::function<JSON::String(JSON::StringView, JSON::StringView)> |
A callback to name what bundling embeds, given the URI of the place it came from and the Components Object member it goes under. Whatever it hands back is held to the keys that the specification admits and to being one the description does not already give a meaning to, so it is what bundling starts from rather than the last word
| std::string_view sourcemeta::core::OpenAPIBundleOptions::default_base {} |
The URI the document was retrieved from, which every relative reference it makes resolves against. A document that names itself takes that name as its base instead, leaving this as the one a relative such name resolves against
| std::uint64_t sourcemeta::core::OpenAPIBundleOptions::max_locations {std::numeric_limits<std::uint64_t>::max()} |
The maximum number of locations that analysis may register. How many documents bundling ends up reading follows from what the resolvers hand back rather than from the document the caller passed in, and every walk and every frame that bundling constructs spends from this one allowance, throwing sourcemeta::core::OpenAPIBundleLimitError once it runs out.
Bundling settles by reading what it has produced so far over and over until a pass brings nothing new in, so this bounds the reading rather than the result. One place counts once per pass that goes by it and once more for each document brought in alongside it, which puts the allowance a whole description needs well above the number of places it holds. Note too that a document is read in full before anything charges for it, so this bounds how many oversized documents are read rather than whether one is
| struct sourcemeta::core::OpenAPIDependency |
What one reference reaches, whether a description or a schema of the span made it. Several of them may name one document, as what is reported is where a reference sits rather than what analysis had to fetch. Whatever a member carries points into something analysis owns only for the call that reports it, so a callback keeping any of them past its own return copies them out
Public Attributes | |
|---|---|
| JSON::StringView | origin |
| JSON::StringView | destination |
| Where it points, resolved and canonicalised, without its fragment. | |
| const JSON * | document |
| OpenAPIObjectKind | expected |
| What the position spelling it expects to find at the far end. | |
| const JSON* sourcemeta::core::OpenAPIDependency::document |
The document that the reference leads to, which is there only where this is the reference that had analysis resolve it. Analysis lets go of what it read as soon as it is done with it, so a reference reaching a document the span already holds, and one that nothing answered for until another document settled it, carry nothing here
| JSON::StringView sourcemeta::core::OpenAPIDependency::origin |
The identifier the document making the reference goes by, which is nothing at all where it declares none and the caller named none
| struct sourcemeta::core::OpenAPIDependencyOptions |
Everything dependency analysis takes beyond the description and how to read it
Public Attributes | |
|---|---|
| std::string_view | default_base {} |
| std::uint64_t | max_locations {std::numeric_limits<std::uint64_t>::max()} |
| std::string_view sourcemeta::core::OpenAPIDependencyOptions::default_base {} |
The URI the document was retrieved from, which its relative references resolve against unless it declares a base of its own
| std::uint64_t sourcemeta::core::OpenAPIDependencyOptions::max_locations {std::numeric_limits<std::uint64_t>::max()} |
The most locations analysis may register before it throws sourcemeta::core::OpenAPIFrameLimitError
| class sourcemeta::core::OpenAPIError |
An error that represents an OpenAPI Description that does not conform to the specification. For example:
Public Member Functions | |
|---|---|
| OpenAPIError (const StaticString message, Pointer location) | |
| Construct an error from a message and where the problem is. | |
| OpenAPIError (const StaticString message, JSON::String base, Pointer location) | |
| auto | location () const noexcept -> const Pointer & |
| auto | base () const noexcept -> JSON::StringView |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
|
inline |
Construct an error that names the document the problem is in, which is what a caller that framed more than one of them tells them apart by
|
inlinenodiscardnoexcept |
|
inlinenodiscardnoexcept |
Get where the problem is, as a pointer from the root of the document that holds it
| class sourcemeta::core::OpenAPIResolutionError |
An error that represents a document of an OpenAPI Description that nothing could produce. For example:
Public Member Functions | |
|---|---|
| OpenAPIResolutionError (const StaticString message, JSON::String base, Pointer location, JSON::String identifier) | |
| auto | identifier () const noexcept -> JSON::StringView |
| The URI that nothing could produce a document for. | |
| auto | location () const noexcept -> const Pointer & |
| auto | base () const noexcept -> JSON::StringView |
| Get the base URI of the document that makes the reference. | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
|
inline |
Create a resolution error from a message, the document the reference was made in, where in it the reference sits, and what it names
|
inlinenodiscardnoexcept |
Get where the reference is, as a pointer from the root of the document that makes it
| class sourcemeta::core::OpenAPIReferenceError |
An error that represents a reference of an OpenAPI Description that names something it may not. For example:
Public Member Functions | |
|---|---|
| OpenAPIReferenceError (const StaticString message, JSON::String base, Pointer location, JSON::String identifier) | |
| auto | identifier () const noexcept -> JSON::StringView |
| The URI that the reference names, resolved and canonicalised. | |
| auto | location () const noexcept -> const Pointer & |
| auto | base () const noexcept -> JSON::StringView |
| Get the base URI of the document that makes the reference. | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
|
inline |
Create a reference error from a message, the document the reference was made in, where in it the reference sits, and what it names
|
inlinenodiscardnoexcept |
Get where the reference is, as a pointer from the root of the document that makes it
| class sourcemeta::core::OpenAPIFrameLimitError |
An error that represents framing that ran past what the caller allowed it to register. For example:
Public Member Functions | |
|---|---|
| OpenAPIFrameLimitError (const std::uint64_t limit) noexcept | |
| Create a framing limit error. | |
| auto | limit () const noexcept -> std::uint64_t |
| The maximum number of locations that framing was allowed to register. | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
| class sourcemeta::core::OpenAPIBundleLimitError |
An error that represents bundling that ran past what the caller allowed it to analyse. For example:
Public Member Functions | |
|---|---|
| OpenAPIBundleLimitError (const std::uint64_t limit) noexcept | |
| Create a bundling limit error. | |
| auto | limit () const noexcept -> std::uint64_t |
| The maximum number of locations that bundling was allowed to register. | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
A callback to report every dependency that analysis finds
| using sourcemeta::core::OpenAPIResolver = std::function<OpenAPIResolverResult(std::string_view)> |
How bundling reaches the other documents that an OpenAPI Description is split across. A URI that names nothing is reported by handing back no value, and whatever else a URI names is handed back as it stands, for bundling to decide whether it is a document a description may span. For example:
What a sourcemeta::core::OpenAPIResolver hands back: either a document it owns, or a reference to one that outlives the call
|
strong |
The OpenAPI Description versions that this module recognises. The enumerators run in the order the revisions were published, so that comparing them says what the specification says when it gives the revision a field arrived in
| Enumerator | |
|---|---|
| OPENAPI_3_0 | The OpenAPI Specification 3.0 revision. |
| OPENAPI_3_1 | The OpenAPI Specification 3.1 revision. |
| OPENAPI_3_2 | The OpenAPI Specification 3.2 revision. |
| SOURCEMETA_CORE_OPENAPI_EXPORT auto sourcemeta::core::openapi_base | ( | const JSON & | document, |
| const std::string_view | retrieval ) -> JSON::String |
The base that every place of an OpenAPI Description is addressed by, given the URI the document was retrieved from. That is the URI the document names itself with, where the revision it declares admits one and what it names can be made absolute, and the retrieval URI canonicalised otherwise. Asking this is how a caller holding one document tells a problem reported within it from one reported in a document reached from it. For example:
A retrieval URI that establishes nothing is given as the empty URI reference, which is answered by whatever the document names itself with, and by the empty URI reference when that is nothing absolute either, leaving every relative reference the description makes relative. Anything else must carry a scheme, as RFC 3986 Section 5.2.1 requires one of a base, and one that does not is refused by throwing sourcemeta::core::OpenAPIError, as reading a description under such a base is refused too
| SOURCEMETA_CORE_OPENAPI_EXPORT auto sourcemeta::core::openapi_bundle | ( | const JSON & | document, |
| const SchemaWalker & | walker, | ||
| const SchemaResolver & | schema_resolver, | ||
| const OpenAPIResolver & | resolver, | ||
| const OpenAPIBundleOptions & | options = {} ) -> JSON |
Bundle an OpenAPI Description by embedding everything it references from another document into its own Components Object. No document the description spans may declare a revision of the OpenAPI Specification other than the one the entry document declares, which is a choice this makes rather than one the specification asks for. This overload returns a new document, without mutating the input. For example:
| SOURCEMETA_CORE_OPENAPI_EXPORT auto sourcemeta::core::openapi_bundle | ( | JSON & | document, |
| const SchemaWalker & | walker, | ||
| const SchemaResolver & | schema_resolver, | ||
| const OpenAPIResolver & | resolver, | ||
| const OpenAPIBundleOptions & | options = {} ) -> void |
Bundle an OpenAPI Description by embedding everything it references from another document into its own Components Object. The walker and the resolver are what reading inside a Schema Object takes, and the OpenAPI resolver is how the rest of the description is reached. No document the description spans may declare a revision of the OpenAPI Specification other than the one the entry document declares. The specification does not ask for that. It is a choice this makes, as what this produces is one document that declares one revision, and there is none to pick that can express both what one revision holds and what another does. This overload mutates the input document. For example:
| SOURCEMETA_CORE_OPENAPI_EXPORT auto sourcemeta::core::openapi_dependencies | ( | const JSON & | document, |
| const SchemaWalker & | walker, | ||
| const SchemaResolver & | schema_resolver, | ||
| const OpenAPIResolver & | resolver, | ||
| const OpenAPIDependencyCallback & | callback, | ||
| const OpenAPIDependencyOptions & | options = {} ) -> std::uint64_t |
Report every reference an OpenAPI Description makes to another document, transitively, whether this specification gives it meaning or JSON Schema does. A document that several references name is reported once for each of them, which leaves a caller wanting one edge per document to take it from there. For example:
Only the reference that had analysis resolve a document carries it, which leaves one reaching a document the span already holds reported with nothing to fetch. A reference that nothing answers for when it is read leads somewhere only once a document that arrived later settles it, so that one is reported after the references of every document read in between, and not at all where it ends analysis instead. A reference that names the document it sits in is that document's own business rather than a dependency, and is reported nowhere. An official JSON Schema dialect is reported where a reference names one and left out where a dialect declaration does, and neither is read.
Analysis throws where it cannot go on, which is wherever the span turns out not to describe one API: a reference nothing answers for, a document that cannot be read as what reached it, or more locations than the allowance permits. Returns what it registered against that allowance, which falls short of what a second run needs wherever a schema walk raised and another document answered for it afterwards.
| SOURCEMETA_CORE_OPENAPI_EXPORT auto sourcemeta::core::openapi_format | ( | JSON & | document, |
| const OpenAPIFrame & | frame ) -> void |
This function reorders an OpenAPI Description in place, following an opinionated OpenAPI aware order, and hands every Schema Object it holds to the JSON Schema formatter. Note that doing so invalidates the given frame, as the locations it holds point into the document. For example:
| SOURCEMETA_CORE_OPENAPI_EXPORT auto sourcemeta::core::openapi_is_document | ( | const JSON & | document | ) | -> bool |
Whether a value declares itself an OpenAPI Description, whichever revision it names and whether or not it holds up as one. This is what tells a description from a schema before either is read. For example:
|
noexcept |
The name that a frame exports a kind of Object as, which is the name the specification gives that Object hyphenated and in lower case. For example:
|
noexcept |
The name that a frame exports a route to an operation as. For example:
| SOURCEMETA_CORE_OPENAPI_EXPORT auto sourcemeta::core::openapi_version | ( | const JSON & | document | ) | -> std::optional< OpenAPIVersion > |
Determine the version of an OpenAPI Description from its OpenAPI field without framing it, returning no value for a version we do not recognise and for anything that declares no such field to read. The patch component of the field carries no meaning, so every 3.1.x release maps to the same result. For example:
|
noexcept |
The feature set a version designates, which OpenAPI Specification 3.1.1, Section 4.1 spells as "the `major`.`minor` portion of the version string". For example:
| SOURCEMETA_CORE_OPENAPI_EXPORT auto sourcemeta::core::openapi_version_string | ( | const JSON & | document | ) | -> std::optional< JSON::StringView > |
The version that an OpenAPI Description declares, exactly as it wrote it, returning no value for anything that declares none. A description naming a revision this module does not recognise reports one here all the same, which is what lets a caller quote it back. The result borrows from the document it was read from, so that document must outlive it. For example: