Sourcemeta Core 0.0.0
Loading...
Searching...
No Matches
OpenAPI

A growing implementation of the OpenAPI Specification. More...

Classes

struct  sourcemeta::core::OpenAPIContact
struct  sourcemeta::core::OpenAPILicense
struct  sourcemeta::core::OpenAPIInfo
class  sourcemeta::core::OpenAPIFrame
struct  sourcemeta::core::OpenAPIBundleOptions
struct  sourcemeta::core::OpenAPIDependency
struct  sourcemeta::core::OpenAPIDependencyOptions
class  sourcemeta::core::OpenAPIError
class  sourcemeta::core::OpenAPIResolutionError
class  sourcemeta::core::OpenAPIReferenceError
class  sourcemeta::core::OpenAPIFrameLimitError
class  sourcemeta::core::OpenAPIBundleLimitError

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

Detailed Description

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:

#include <sourcemeta/core/openapi.h>

Class Documentation

◆ sourcemeta::core::OpenAPIContact

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.

◆ sourcemeta::core::OpenAPILicense

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.

Member Data Documentation

◆ identifier

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

◆ sourcemeta::core::OpenAPIInfo

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.

Member Data Documentation

◆ version

JSON::StringView sourcemeta::core::OpenAPIInfo::version {}

The version of the document, which is unrelated to the version of the OpenAPI Specification that it declares

◆ sourcemeta::core::OpenAPIFrame

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:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <iostream>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {}
})")};
sourcemeta::core::prettify(frame.to_json(), std::cout);
std::cout << std::endl;
SOURCEMETA_CORE_JSON_EXPORT auto parse_json(std::basic_istream< JSON::Char, JSON::CharTraits > &stream, std::uint32_t maximum_input_bytes=JSON_MAXIMUM_INPUT_BYTES) -> JSON
SOURCEMETA_CORE_JSON_EXPORT auto prettify(const JSON &document, std::basic_ostream< JSON::Char, JSON::CharTraits > &stream, const std::size_t spaces=2) -> void
SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto schema_resolver(const std::string_view identifier) -> SchemaResolverResult
SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto schema_walker(const std::string_view keyword, const SchemaVocabularies &vocabularies) -> const SchemaWalkerResult &
auto to_json(const std::optional< PointerPositionTracker > &tracker=std::nullopt) const -> JSON
Definition openapi.h:257

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

Member Typedef Documentation

◆ Locations

The Objects a frame holds, keyed by the URI addressing each one. Comparison is transparent so that a lookup may take a view of a URI without building a string of it

◆ References

The references a frame holds, keyed by the URI of the Object that makes each one

Constructor & Destructor Documentation

◆ OpenAPIFrame()

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

Member Function Documentation

◆ any_object()

template<std::predicate< const JSON::String &, const Location & > F>
auto sourcemeta::core::OpenAPIFrame::any_object ( const F & predicate) const -> bool
inlinenodiscard

Check whether any Object the description holds satisfies the predicate. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {}
})")};
assert(frame.any_object([](const auto &, const auto &location) {
return location.type ==
sourcemeta::core::OpenAPIFrame::ObjectKind::Paths;
}));
auto any_object(const F &predicate) const -> bool
Definition openapi.h:659

◆ base()

auto sourcemeta::core::OpenAPIFrame::base ( ) const -> JSON::StringView
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:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {}
})")};
"https://example.com/openapi.json"};
assert(frame.base() == "https://example.com/openapi.json");
auto base() const noexcept -> JSON::StringView

◆ discriminators()

auto sourcemeta::core::OpenAPIFrame::discriminators ( ) const -> const std::vector< Discriminator > &
nodiscardnoexcept

Every URI a Discriminator Object names, which is a reference the schemas hold rather than one the shell around them does

◆ for_each_discriminator()

template<std::invocable< const Discriminator & > F>
auto sourcemeta::core::OpenAPIFrame::for_each_discriminator ( const F & callback) const -> void
inline

Iterate over every URI a Discriminator Object names. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <iostream>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {}
})")};
frame.for_each_discriminator([](const auto &discriminator) {
std::cout << discriminator.destination << "\n";
});
auto for_each_discriminator(const F &callback) const -> void
Definition openapi.h:780

◆ for_each_object()

template<std::invocable< const JSON::String &, const Location & > F>
auto sourcemeta::core::OpenAPIFrame::for_each_object ( const F & callback) const -> void
inline

Iterate over every Object the description holds, along with the URI the frame keys it by. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <iostream>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {}
})")};
frame.for_each_object([](const auto &uri, const auto &location) {
if (location.type ==
sourcemeta::core::OpenAPIFrame::ObjectKind::Schema) {
std::cout << "a schema at " << uri << "\n";
}
});
auto for_each_object(const F &callback) const -> void
Definition openapi.h:629
auto uri(const Pointer &pointer) const -> JSON::String

◆ for_each_operation()

template<std::invocable< const Operation & > F>
auto sourcemeta::core::OpenAPIFrame::for_each_operation ( const F & callback) const -> void
inline

Iterate over every operation the described API exposes. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <iostream>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": { "/users": { "get": { "responses": {
"200": { "description": "Some users" } } } } }
})")};
frame.for_each_operation([](const auto &operation) {
std::cout << operation.method << " " << operation.path << "\n";
});
auto for_each_operation(const F &callback) const -> void
Definition openapi.h:752

◆ for_each_reference()

template<std::invocable< const JSON::String &, const Reference & > F>
auto sourcemeta::core::OpenAPIFrame::for_each_reference ( const F & callback) const -> void
inline

Iterate over every reference the description makes, along with the URI of the Object that makes it. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <iostream>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": { "/users": { "$ref": "#/components/pathItems/Users" } },
"components": { "pathItems": { "Users": {} } }
})")};
frame.for_each_reference([](const auto &origin, const auto &reference) {
std::cout << origin << " -> " << reference.destination << "\n";
});
auto for_each_reference(const F &callback) const -> void
Definition openapi.h:693

◆ for_each_security_reference()

template<std::invocable< const JSON::String &, const Reference & > F>
auto sourcemeta::core::OpenAPIFrame::for_each_security_reference ( const F & callback) const -> void
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:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <iostream>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {}
})")};
[](const auto &origin, const auto &reference) {
std::cout << origin << " -> " << reference.destination << "\n";
});
auto for_each_security_reference(const F &callback) const -> void
Definition openapi.h:723

◆ info()

auto sourcemeta::core::OpenAPIFrame::info ( ) const -> const OpenAPIInfo &
nodiscardnoexcept

Get the metadata that the entry document declares about the API. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {}
})")};
assert(frame.info().title == "Example");
assert(frame.info().version == "1.0.0");
assert(!frame.info().license.has_value());
auto info() const noexcept -> const OpenAPIInfo &

◆ reference_count()

auto sourcemeta::core::OpenAPIFrame::reference_count ( ) const -> std::size_t
nodiscardnoexcept

How many references the description makes, not counting what a Security Requirement Object names by the URI of a scheme

◆ references()

auto sourcemeta::core::OpenAPIFrame::references ( ) const -> const References &
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

◆ schemas()

auto sourcemeta::core::OpenAPIFrame::schemas ( ) const -> const SchemaFrame &
nodiscardnoexcept

Get the frame of every Schema Object the description holds, which a schema location names its part of by key. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"components": { "schemas": { "Pet": { "type": "object" } } }
})")};
"https://example.com/openapi.json"};
assert(frame.schemas()
"https://example.com/openapi.json"
"#/components/schemas/Pet")
.has_value());
@ Static
A reference that resolves at framing time.
Definition jsonschema_types.h:47
auto schemas() const noexcept -> const SchemaFrame &

◆ security_references()

auto sourcemeta::core::OpenAPIFrame::security_references ( ) const -> const References &
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

◆ standalone()

auto sourcemeta::core::OpenAPIFrame::standalone ( ) const -> bool
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:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {}
})")};
assert(frame.standalone());
auto standalone() const noexcept -> bool

◆ to_json()

auto sourcemeta::core::OpenAPIFrame::to_json ( const std::optional< PointerPositionTracker > & tracker = std::nullopt) const -> JSON
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:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {}
})")};
assert(frame.to_json().at("version").to_string() == "3.1");

◆ traverse()

auto sourcemeta::core::OpenAPIFrame::traverse ( const JSON::StringView uri) const -> const Location *
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:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {}
})")};
"https://example.com/openapi.json"};
assert(frame.traverse("https://example.com/openapi.json#/info")->type ==
sourcemeta::core::OpenAPIFrame::ObjectKind::Info);
auto traverse(const JSON::StringView uri) const -> const Location *

◆ uri()

auto sourcemeta::core::OpenAPIFrame::uri ( const Pointer & pointer) const -> JSON::String
nodiscard

The URI this frame addresses the given position by, which is the inverse of traversal. For example:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {}
})")};
"https://example.com/openapi.json"};
assert(frame.uri(sourcemeta::core::Pointer{"info"}) ==
"https://example.com/openapi.json#/info");
GenericPointer< JSON::String, PropertyHashJSON< JSON::String > > Pointer
Definition jsonpointer.h:41

◆ version()

auto sourcemeta::core::OpenAPIFrame::version ( ) const -> OpenAPIVersion
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:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {}
})")};
assert(frame.version() ==
auto version() const noexcept -> OpenAPIVersion
@ OPENAPI_3_1
The OpenAPI Specification 3.1 revision.
Definition openapi.h:52

◆ sourcemeta::core::OpenAPIBundleOptions

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.

Member Typedef Documentation

◆ Callback

Initial value:
std::function<void(JSON::StringView, const sourcemeta::core::Pointer &)>
std::basic_string_view< Char, CharTraits > StringView
The string view type used by the JSON document.
Definition json_value.h:54

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

◆ Namer

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

Member Data Documentation

◆ default_base

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

◆ max_locations

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

◆ sourcemeta::core::OpenAPIDependency

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.

Member Data Documentation

◆ document

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

◆ origin

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

◆ sourcemeta::core::OpenAPIDependencyOptions

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()}

Member Data Documentation

◆ default_base

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

◆ max_locations

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

◆ sourcemeta::core::OpenAPIError

class sourcemeta::core::OpenAPIError

An error that represents an OpenAPI Description that does not conform to the specification. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
"The Info Object is required", sourcemeta::core::Pointer{"info"}};
assert(error.location() == sourcemeta::core::Pointer{"info"});
auto location() const noexcept -> const Pointer &
Definition openapi_error.h:46
Definition openapi_error.h:32
Inheritance diagram for sourcemeta::core::OpenAPIError:
sourcemeta::core::Error

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.

Constructor & Destructor Documentation

◆ OpenAPIError()

sourcemeta::core::OpenAPIError::OpenAPIError ( const StaticString message,
JSON::String base,
Pointer location )
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

Member Function Documentation

◆ base()

auto sourcemeta::core::OpenAPIError::base ( ) const -> JSON::StringView
inlinenodiscardnoexcept

Get the base URI of the document that holds the problem, or the empty URI reference when the caller established none

◆ location()

auto sourcemeta::core::OpenAPIError::location ( ) const -> const Pointer &
inlinenodiscardnoexcept

Get where the problem is, as a pointer from the root of the document that holds it

◆ sourcemeta::core::OpenAPIResolutionError

class sourcemeta::core::OpenAPIResolutionError

An error that represents a document of an OpenAPI Description that nothing could produce. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
"Could not resolve", "https://example.com/openapi.json",
sourcemeta::core::Pointer{"$ref"}, "https://example.com/shared.json"};
assert(error.identifier() == "https://example.com/shared.json");
auto identifier() const noexcept -> JSON::StringView
The URI that nothing could produce a document for.
Definition openapi_error.h:85
Definition openapi_error.h:75
Inheritance diagram for sourcemeta::core::OpenAPIResolutionError:
sourcemeta::core::Error

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.

Constructor & Destructor Documentation

◆ OpenAPIResolutionError()

sourcemeta::core::OpenAPIResolutionError::OpenAPIResolutionError ( const StaticString message,
JSON::String base,
Pointer location,
JSON::String identifier )
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

Member Function Documentation

◆ location()

auto sourcemeta::core::OpenAPIResolutionError::location ( ) const -> const Pointer &
inlinenodiscardnoexcept

Get where the reference is, as a pointer from the root of the document that makes it

◆ sourcemeta::core::OpenAPIReferenceError

class sourcemeta::core::OpenAPIReferenceError

An error that represents a reference of an OpenAPI Description that names something it may not. For example:

#include <sourcemeta/core/jsonpointer.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
"Wrong kind", "https://example.com/openapi.json",
"https://example.com/shared.json#/info"};
assert(error.identifier() == "https://example.com/shared.json#/info");
auto identifier() const noexcept -> JSON::StringView
The URI that the reference names, resolved and canonicalised.
Definition openapi_error.h:131
Definition openapi_error.h:121
Inheritance diagram for sourcemeta::core::OpenAPIReferenceError:
sourcemeta::core::Error

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.

Constructor & Destructor Documentation

◆ OpenAPIReferenceError()

sourcemeta::core::OpenAPIReferenceError::OpenAPIReferenceError ( const StaticString message,
JSON::String base,
Pointer location,
JSON::String identifier )
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

Member Function Documentation

◆ location()

auto sourcemeta::core::OpenAPIReferenceError::location ( ) const -> const Pointer &
inlinenodiscardnoexcept

Get where the reference is, as a pointer from the root of the document that makes it

◆ sourcemeta::core::OpenAPIFrameLimitError

class sourcemeta::core::OpenAPIFrameLimitError

An error that represents framing that ran past what the caller allowed it to register. For example:

#include <sourcemeta/core/openapi.h>
#include <cassert>
assert(error.limit() == 100);
auto limit() const noexcept -> std::uint64_t
The maximum number of locations that framing was allowed to register.
Definition openapi_error.h:172
Definition openapi_error.h:163
Inheritance diagram for sourcemeta::core::OpenAPIFrameLimitError:
sourcemeta::core::Error

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.

◆ sourcemeta::core::OpenAPIBundleLimitError

class sourcemeta::core::OpenAPIBundleLimitError

An error that represents bundling that ran past what the caller allowed it to analyse. For example:

#include <sourcemeta/core/openapi.h>
#include <cassert>
assert(error.limit() == 100);
auto limit() const noexcept -> std::uint64_t
The maximum number of locations that bundling was allowed to register.
Definition openapi_error.h:200
Definition openapi_error.h:191
Inheritance diagram for sourcemeta::core::OpenAPIBundleLimitError:
sourcemeta::core::Error

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.

Typedef Documentation

◆ OpenAPIDependencyCallback

Initial value:
std::function<void(const OpenAPIDependency &)>
Definition openapi_dependencies.h:29

A callback to report every dependency that analysis finds

◆ OpenAPIResolver

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:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <string_view>
static auto resolver(const std::string_view identifier)
if (identifier == "https://example.com/shared.json") {
"openapi": "3.1.1",
"info": { "title": "Shared", "version": "1.0.0" },
"components": {}
})JSON");
}
return std::nullopt;
}
OwnedOrReference< JSON > OpenAPIResolverResult
Definition openapi_types.h:140

◆ OpenAPIResolverResult

What a sourcemeta::core::OpenAPIResolver hands back: either a document it owns, or a reference to one that outlives the call

Enumeration Type Documentation

◆ OpenAPIVersion

enum class sourcemeta::core::OpenAPIVersion : std::uint8_t
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.

Function Documentation

◆ openapi_base()

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:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.2.0",
"$self": "https://example.com/api",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {}
})")};
document, "https://example.com/openapi.json") ==
"https://example.com/api");
SOURCEMETA_CORE_OPENAPI_EXPORT auto openapi_base(const JSON &document, const std::string_view retrieval) -> JSON::String

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

◆ openapi_bundle() [1/2]

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:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
#include <string_view>
static auto resolver(const std::string_view identifier)
assert(identifier == "https://example.com/shared.json");
"openapi": "3.1.1",
"info": { "title": "Shared", "version": "1.0.0" },
"components": {
"responses": { "NotFound": { "description": "Not found" } }
}
})JSON");
}
const auto document{sourcemeta::core::parse_json(R"JSON({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {
"/pets": {
"get": {
"responses": {
"404": { "$ref": "shared.json#/components/responses/NotFound" }
}
}
}
}
})JSON")};
{.default_base = "https://example.com/openapi.json"})};
assert(result.at("components").at("responses").defines("NotFound"));
SOURCEMETA_CORE_OPENAPI_EXPORT auto openapi_bundle(JSON &document, const SchemaWalker &walker, const SchemaResolver &schema_resolver, const OpenAPIResolver &resolver, const OpenAPIBundleOptions &options={}) -> void

◆ openapi_bundle() [2/2]

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:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
#include <string_view>
static auto resolver(const std::string_view identifier)
assert(identifier == "https://example.com/shared.json");
"openapi": "3.1.1",
"info": { "title": "Shared", "version": "1.0.0" },
"components": {
"responses": { "NotFound": { "description": "Not found" } }
}
})JSON");
}
auto document{sourcemeta::core::parse_json(R"JSON({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {
"/pets": {
"get": {
"responses": {
"404": { "$ref": "shared.json#/components/responses/NotFound" }
}
}
}
}
})JSON")};
{.default_base = "https://example.com/openapi.json"});
assert(document.at("components").at("responses").defines("NotFound"));

◆ openapi_dependencies()

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:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
// A resolver that knows the other document of this description
static auto shared_resolver(std::string_view identifier)
if (identifier == "https://www.example.com/shared.json") {
"openapi": "3.1.1",
"info": { "title": "Shared", "version": "1.0.0" },
"paths": { "/thing": { "description": "Shared" } }
})JSON");
}
return std::nullopt;
}
const auto document = sourcemeta::core::parse_json(R"JSON({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {
"/thing": {
"$ref": "https://www.example.com/shared.json#/paths/~1thing"
}
}
})JSON");
shared_resolver,
[](const auto &dependency) {
// Do something with the information
});
SOURCEMETA_CORE_OPENAPI_EXPORT auto openapi_dependencies(const JSON &document, const SchemaWalker &walker, const SchemaResolver &schema_resolver, const OpenAPIResolver &resolver, const OpenAPIDependencyCallback &callback, const OpenAPIDependencyOptions &options={}) -> std::uint64_t

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.

◆ openapi_format()

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:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/jsonschema.h>
#include <sourcemeta/core/openapi.h>
#include <iostream>
auto document = sourcemeta::core::parse_json(R"JSON({
"info": { "version": "1.0.0", "title": "Example" },
"paths": {},
"openapi": "3.1.1"
})JSON");
sourcemeta::core::prettify(document, std::cout);
SOURCEMETA_CORE_OPENAPI_EXPORT auto openapi_format(JSON &document, const OpenAPIFrame &frame) -> void

◆ openapi_is_document()

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:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {}
})")};
SOURCEMETA_CORE_OPENAPI_EXPORT auto openapi_is_document(const JSON &document) -> bool

◆ openapi_kind_name()

SOURCEMETA_CORE_OPENAPI_EXPORT auto sourcemeta::core::openapi_kind_name ( const OpenAPIObjectKind kind) -> JSON::StringView
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:

#include <sourcemeta/core/openapi.h>
#include <cassert>
sourcemeta::core::OpenAPIObjectKind::PathItem) ==
"path-item");
SOURCEMETA_CORE_OPENAPI_EXPORT auto openapi_kind_name(const OpenAPIObjectKind kind) noexcept -> JSON::StringView

◆ openapi_operation_kind_name()

SOURCEMETA_CORE_OPENAPI_EXPORT auto sourcemeta::core::openapi_operation_kind_name ( const OpenAPIOperationKind kind) -> JSON::StringView
noexcept

The name that a frame exports a route to an operation as. For example:

#include <sourcemeta/core/openapi.h>
#include <cassert>
sourcemeta::core::OpenAPIOperationKind::Webhook) ==
"webhook");
SOURCEMETA_CORE_OPENAPI_EXPORT auto openapi_operation_kind_name(const OpenAPIOperationKind kind) noexcept -> JSON::StringView

◆ openapi_version()

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:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.1.1",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {}
})")};
assert(sourcemeta::core::openapi_version(document).value() ==
SOURCEMETA_CORE_OPENAPI_EXPORT auto openapi_version(const JSON &document) -> std::optional< OpenAPIVersion >

◆ openapi_version_name()

SOURCEMETA_CORE_OPENAPI_EXPORT auto sourcemeta::core::openapi_version_name ( const OpenAPIVersion version) -> JSON::StringView
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:

#include <sourcemeta/core/openapi.h>
#include <cassert>
SOURCEMETA_CORE_OPENAPI_EXPORT auto openapi_version_name(const OpenAPIVersion version) noexcept -> JSON::StringView

◆ openapi_version_string()

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:

#include <sourcemeta/core/json.h>
#include <sourcemeta/core/openapi.h>
#include <cassert>
const auto document{sourcemeta::core::parse_json(R"({
"openapi": "3.3.0",
"info": { "title": "Example", "version": "1.0.0" },
"paths": {}
})")};
assert(sourcemeta::core::openapi_version_string(document).value() ==
"3.3.0");
assert(!sourcemeta::core::openapi_version(document).has_value());
SOURCEMETA_CORE_OPENAPI_EXPORT auto openapi_version_string(const JSON &document) -> std::optional< JSON::StringView >