Sourcemeta Core 0.0.0
Loading...
Searching...
No Matches
openapi.h
1#ifndef SOURCEMETA_CORE_OPENAPI_H_
2#define SOURCEMETA_CORE_OPENAPI_H_
3
4#ifndef SOURCEMETA_CORE_OPENAPI_EXPORT
5#include <sourcemeta/core/openapi_export.h>
6#endif
7
8#include <sourcemeta/core/json.h>
9#include <sourcemeta/core/jsonpointer.h>
10#include <sourcemeta/core/jsonschema.h>
11
12// NOLINTBEGIN(misc-include-cleaner)
13#include <sourcemeta/core/openapi_dependencies.h>
14#include <sourcemeta/core/openapi_error.h>
15#include <sourcemeta/core/openapi_types.h>
16// NOLINTEND(misc-include-cleaner)
17
18#include <concepts> // std::invocable, std::predicate
19#include <cstddef> // std::size_t
20#include <cstdint> // std::uint8_t, std::uint64_t
21#include <functional> // std::function, std::less
22#include <limits> // std::numeric_limits
23#include <map> // std::map
24#include <memory> // std::unique_ptr
25#include <optional> // std::optional, std::nullopt
26#include <string_view> // std::string_view
27#include <vector> // std::vector
28
40
41namespace sourcemeta::core {
42
56
78SOURCEMETA_CORE_OPENAPI_EXPORT
79auto openapi_version(const JSON &document) -> std::optional<OpenAPIVersion>;
80
93SOURCEMETA_CORE_OPENAPI_EXPORT
94auto openapi_version_name(const OpenAPIVersion version) noexcept
96
119SOURCEMETA_CORE_OPENAPI_EXPORT
120auto openapi_version_string(const JSON &document)
121 -> std::optional<JSON::StringView>;
122
141SOURCEMETA_CORE_OPENAPI_EXPORT
142auto openapi_is_document(const JSON &document) -> bool;
143
176SOURCEMETA_CORE_OPENAPI_EXPORT
177auto openapi_base(const JSON &document, const std::string_view retrieval)
178 -> JSON::String;
179
186 std::optional<JSON::StringView> name{std::nullopt};
188 std::optional<JSON::StringView> url{std::nullopt};
190 std::optional<JSON::StringView> email{std::nullopt};
191};
192
202 std::optional<JSON::StringView> identifier{std::nullopt};
204 std::optional<JSON::StringView> url{std::nullopt};
205};
206
218 std::optional<JSON::StringView> summary{std::nullopt};
220 std::optional<JSON::StringView> description{std::nullopt};
222 std::optional<JSON::StringView> terms_of_service{std::nullopt};
224 std::optional<OpenAPIContact> contact{std::nullopt};
226 std::optional<OpenAPILicense> license{std::nullopt};
227};
228
257class SOURCEMETA_CORE_OPENAPI_EXPORT OpenAPIFrame {
258public:
260 using ObjectKind = OpenAPIObjectKind;
262 using OperationKind = OpenAPIOperationKind;
263
286
289 struct Operation {
310 std::optional<JSON::String> parent{std::nullopt};
314 std::vector<JSON::String> servers;
316 std::vector<JSON::String> security;
320 std::vector<JSON::String> parameters;
325 std::vector<std::optional<JSON::String>> tags;
326 };
327
353
356 struct Location {
360 Pointer pointer;
365 std::optional<JSON::StringView> parent{std::nullopt};
378 };
379
383 using Locations = std::map<JSON::String, Location, std::less<>>;
384
387 using References = std::map<JSON::String, Reference, std::less<>>;
388
443 const JSON &document, const SchemaWalker &walker,
444 const SchemaResolver &resolver, const std::string_view default_base = "",
445 std::uint64_t max_locations = std::numeric_limits<std::uint64_t>::max(),
446 const OpenAPIFrame *entry = nullptr);
447
449
450 // We rely on internal caches that would be dangling otherwise
451 OpenAPIFrame(const OpenAPIFrame &) = delete;
452 auto operator=(const OpenAPIFrame &) -> OpenAPIFrame & = delete;
453 OpenAPIFrame(OpenAPIFrame &&) = delete;
454 auto operator=(OpenAPIFrame &&) -> OpenAPIFrame & = delete;
455
477 [[nodiscard]] auto version() const noexcept -> OpenAPIVersion;
478
500 [[nodiscard]] auto info() const noexcept -> const OpenAPIInfo &;
501
526 [[nodiscard]] auto base() const noexcept -> JSON::StringView;
527
550 [[nodiscard]] auto standalone() const noexcept -> bool;
551
577 [[nodiscard]] auto schemas() const noexcept -> const SchemaFrame &;
578
580 [[nodiscard]] auto locations() const noexcept -> const Locations &;
581
585 [[nodiscard]] auto references() const noexcept -> const References &;
586
592 [[nodiscard]] auto security_references() const noexcept -> const References &;
593
595 [[nodiscard]] auto operations() const noexcept
596 -> const std::vector<Operation> &;
597
600 [[nodiscard]] auto discriminators() const noexcept
601 -> const std::vector<Discriminator> &;
602
628 template <std::invocable<const JSON::String &, const Location &> F>
629 auto for_each_object(const F &callback) const -> void {
630 for (const auto &entry : this->locations()) {
631 callback(entry.first, entry.second);
632 }
633 }
634
658 template <std::predicate<const JSON::String &, const Location &> F>
659 [[nodiscard]] auto any_object(const F &predicate) const -> bool {
660 for (const auto &entry : this->locations()) {
661 if (predicate(entry.first, entry.second)) {
662 return true;
663 }
664 }
665
666 return false;
667 }
668
692 template <std::invocable<const JSON::String &, const Reference &> F>
693 auto for_each_reference(const F &callback) const -> void {
694 for (const auto &entry : this->references()) {
695 callback(entry.first, entry.second);
696 }
697 }
698
722 template <std::invocable<const JSON::String &, const Reference &> F>
723 auto for_each_security_reference(const F &callback) const -> void {
724 for (const auto &entry : this->security_references()) {
725 callback(entry.first, entry.second);
726 }
727 }
728
751 template <std::invocable<const Operation &> F>
752 auto for_each_operation(const F &callback) const -> void {
753 for (const auto &operation : this->operations()) {
754 callback(operation);
755 }
756 }
757
779 template <std::invocable<const Discriminator &> F>
780 auto for_each_discriminator(const F &callback) const -> void {
781 for (const auto &discriminator : this->discriminators()) {
782 callback(discriminator);
783 }
784 }
785
810 [[nodiscard]] auto traverse(const JSON::StringView uri) const
811 -> const Location *;
812
835 [[nodiscard]] auto uri(const Pointer &pointer) const -> JSON::String;
836
838 [[nodiscard]] auto object_count() const noexcept -> std::size_t;
839
842 [[nodiscard]] auto reference_count() const noexcept -> std::size_t;
843
872 [[nodiscard]] auto to_json(
873 const std::optional<PointerPositionTracker> &tracker = std::nullopt) const
874 -> JSON;
875
876private:
877// Exporting symbols that depends on the standard C++ library is considered
878// safe.
879// https://learn.microsoft.com/en-us/cpp/error-messages/compiler-warnings/compiler-warning-level-2-c4275?view=msvc-170&redirectedfrom=MSDN
880#if defined(_MSC_VER)
881#pragma warning(push)
882#pragma warning(disable : 4251)
883#endif
884 struct Internal;
885 std::unique_ptr<Internal> internal_;
886#if defined(_MSC_VER)
887#pragma warning(pop)
888#endif
889};
890
918SOURCEMETA_CORE_OPENAPI_EXPORT
919auto openapi_format(JSON &document, const OpenAPIFrame &frame) -> void;
920
928 using Callback =
929 std::function<void(JSON::StringView, const sourcemeta::core::Pointer &)>;
930
937
942 std::string_view default_base{};
957 std::uint64_t max_locations{std::numeric_limits<std::uint64_t>::max()};
962};
963
1015SOURCEMETA_CORE_OPENAPI_EXPORT
1016auto openapi_bundle(JSON &document, const SchemaWalker &walker,
1018 const OpenAPIResolver &resolver,
1019 const OpenAPIBundleOptions &options = {}) -> void;
1020
1068SOURCEMETA_CORE_OPENAPI_EXPORT
1069auto openapi_bundle(const JSON &document, const SchemaWalker &walker,
1071 const OpenAPIResolver &resolver,
1072 const OpenAPIBundleOptions &options = {}) -> JSON;
1073
1074} // namespace sourcemeta::core
1075
1076#endif
std::basic_string< Char, CharTraits, Allocator< Char > > String
The string type used by the JSON document.
Definition json_value.h:52
std::basic_string_view< Char, CharTraits > StringView
The string view type used by the JSON document.
Definition json_value.h:54
Definition json_value.h:39
Definition jsonpointer_position.h:51
GenericPointer< JSON::String, PropertyHashJSON< JSON::String > > Pointer
Definition jsonpointer.h:41
Definition jsonschema_frame.h:57
SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto schema_resolver(const std::string_view identifier) -> SchemaResolverResult
std::function< SchemaResolverResult(std::string_view)> SchemaResolver
Definition jsonschema_types.h:41
std::function< const SchemaWalkerResult &( std::string_view, const SchemaVocabularies &)> SchemaWalker
Definition jsonschema_types.h:254
std::string_view default_base
Definition openapi.h:942
OpenAPIOperationKind OperationKind
How an Operation Object is reached from the entry document.
Definition openapi.h:262
auto base() const noexcept -> JSON::StringView
std::optional< JSON::StringView > url
Where to find the contact information, as a URI reference.
Definition openapi.h:188
auto for_each_security_reference(const F &callback) const -> void
Definition openapi.h:723
std::optional< OpenAPIContact > contact
The contact information for the API.
Definition openapi.h:224
auto info() const noexcept -> const OpenAPIInfo &
auto schemas() const noexcept -> const SchemaFrame &
auto for_each_object(const F &callback) const -> void
Definition openapi.h:629
std::optional< JSON::StringView > summary
A short summary of the API.
Definition openapi.h:218
auto operations() const noexcept -> const std::vector< Operation > &
Every operation the described API exposes.
std::optional< OpenAPILicense > license
The license information for the API.
Definition openapi.h:226
auto for_each_discriminator(const F &callback) const -> void
Definition openapi.h:780
std::optional< JSON::StringView > url
Where to find the license used for the API, as a URI reference.
Definition openapi.h:204
JSON::StringView version
Definition openapi.h:216
Callback callback
A callback to report each place that bundling embedded.
Definition openapi.h:959
auto locations() const noexcept -> const Locations &
Every Object the description holds, keyed by the URI addressing each one.
std::optional< JSON::StringView > name
The identifying name of the contact person or organisation.
Definition openapi.h:186
Namer namer
A callback to name each place that bundling embeds.
Definition openapi.h:961
JSON::StringView name
The license name used for the API.
Definition openapi.h:199
std::uint64_t max_locations
Definition openapi.h:957
auto object_count() const noexcept -> std::size_t
How many Objects the description holds.
auto discriminators() const noexcept -> const std::vector< Discriminator > &
OpenAPIObjectKind ObjectKind
What kind of Object a position holds.
Definition openapi.h:260
auto for_each_operation(const F &callback) const -> void
Definition openapi.h:752
auto standalone() const noexcept -> bool
auto any_object(const F &predicate) const -> bool
Definition openapi.h:659
auto for_each_reference(const F &callback) const -> void
Definition openapi.h:693
auto references() const noexcept -> const References &
auto uri(const Pointer &pointer) const -> JSON::String
std::optional< JSON::StringView > identifier
Definition openapi.h:202
auto traverse(const JSON::StringView uri) const -> const Location *
auto security_references() const noexcept -> const References &
std::optional< JSON::StringView > email
The email address of the contact person or organisation.
Definition openapi.h:190
auto reference_count() const noexcept -> std::size_t
std::map< JSON::String, Location, std::less<> > Locations
Definition openapi.h:383
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)
std::function< JSON::String(JSON::StringView, JSON::StringView)> Namer
Definition openapi.h:936
std::optional< JSON::StringView > terms_of_service
Where to find the terms of service for the API, as a URI reference.
Definition openapi.h:222
auto version() const noexcept -> OpenAPIVersion
JSON::StringView title
The title of the API.
Definition openapi.h:213
std::map< JSON::String, Reference, std::less<> > References
Definition openapi.h:387
auto to_json(const std::optional< PointerPositionTracker > &tracker=std::nullopt) const -> JSON
std::optional< JSON::StringView > description
A description of the API, which may be written in CommonMark.
Definition openapi.h:220
std::function< void(JSON::StringView, const sourcemeta::core::Pointer &)> Callback
Definition openapi.h:928
Definition openapi.h:257
SOURCEMETA_CORE_OPENAPI_EXPORT auto openapi_is_document(const JSON &document) -> bool
SOURCEMETA_CORE_OPENAPI_EXPORT auto openapi_base(const JSON &document, const std::string_view retrieval) -> JSON::String
SOURCEMETA_CORE_OPENAPI_EXPORT auto openapi_version_string(const JSON &document) -> std::optional< JSON::StringView >
SOURCEMETA_CORE_OPENAPI_EXPORT auto openapi_bundle(JSON &document, const SchemaWalker &walker, const SchemaResolver &schema_resolver, const OpenAPIResolver &resolver, const OpenAPIBundleOptions &options={}) -> void
SOURCEMETA_CORE_OPENAPI_EXPORT auto openapi_version(const JSON &document) -> std::optional< OpenAPIVersion >
SOURCEMETA_CORE_OPENAPI_EXPORT auto openapi_version_name(const OpenAPIVersion version) noexcept -> JSON::StringView
SOURCEMETA_CORE_OPENAPI_EXPORT auto openapi_format(JSON &document, const OpenAPIFrame &frame) -> void
OpenAPIVersion
Definition openapi.h:48
std::function< OpenAPIResolverResult(std::string_view)> OpenAPIResolver
Definition openapi_types.h:167
@ OPENAPI_3_0
The OpenAPI Specification 3.0 revision.
Definition openapi.h:50
@ OPENAPI_3_2
The OpenAPI Specification 3.2 revision.
Definition openapi.h:54
@ OPENAPI_3_1
The OpenAPI Specification 3.1 revision.
Definition openapi.h:52
Definition openapi.h:184
Definition openapi.h:211
Definition openapi.h:197
bool by_name
Definition openapi.h:347
Pointer origin
Where the mapping value sits, as a pointer from the root of the document.
Definition openapi.h:335
JSON::String destination
Where it points, resolved and canonicalised.
Definition openapi.h:337
JSON::String scope
Definition openapi.h:341
bool dangling
Definition openapi.h:351
JSON::String base
Definition openapi.h:377
ObjectKind type
What kind of Object sits here.
Definition openapi.h:358
std::optional< JSON::StringView > parent
Definition openapi.h:365
JSON::String default_dialect
Definition openapi.h:371
JSON::String method
The method it answers to, as the field that declares it is spelled.
Definition openapi.h:296
std::vector< JSON::String > security
Where the Security Requirement Objects in force sit.
Definition openapi.h:316
std::vector< JSON::String > parameters
Definition openapi.h:320
std::vector< std::optional< JSON::String > > tags
Definition openapi.h:325
JSON::String origin
Where the Operation Object sits.
Definition openapi.h:298
std::optional< JSON::String > parent
Definition openapi.h:310
JSON::String path
Definition openapi.h:294
JSON::String endpoint
Definition openapi.h:302
std::vector< JSON::String > servers
Definition openapi.h:314
OperationKind kind
How the entry document exposes it.
Definition openapi.h:291
bool dangling
Definition openapi.h:277
JSON::String original
The value as the document wrote it.
Definition openapi.h:270
Pointer origin
Definition openapi.h:284
ObjectKind expected
Definition openapi.h:281
JSON::String destination
Definition openapi.h:274