=pod

=encoding UTF-8

=head1 NAME

OpenAPI::Modern - Validate HTTP requests and responses against an OpenAPI v3.1 document

=head1 VERSION

version 0.073

=head1 SYNOPSIS

my $openapi = OpenAPI::Modern->new( openapi_uri => '/api', openapi_schema => YAML::PP->new(boolean => 'JSON::PP')->load_string(<<'YAML')); openapi: 3.1.0 info: title: Test API version: 1.2.3 paths: /foo/{foo_id}: parameters:

• name: foo_id in: path required: true schema: pattern: ^[a-z]+$ post: operationId: my_foo_request parameters:

  • name: My-Request-Header in: header required: true schema: pattern: ^[0-9]+$ requestBody: required: true content: application/json: schema: type: object properties: hello: type: string pattern: ^[0-9]+$ responses: 200: description: success headers: My-Response-Header: required: true schema: pattern: ^[0-9]+$ content: application/json: schema: type: object required: [ status ] properties: status: const: ok YAML

  say 'request:'; my $request = POST '/foo/bar', 'My-Request-Header' => '123', 'Content-Type' => 'application/json', Host => 'example.com', Content => '{"hello": 123}'; my $results = $openapi->validate_request($request); say $results; say ''; # newline say JSON::MaybeXS->new(convert_blessed => 1, canonical => 1, pretty => 1, indent_length => 2)->encode($results);

  say 'response:'; my $response = Mojo::Message::Response->new(code => 200, message => 'OK'); $response->headers->content_type('application/json'); $response->headers->header('My-Response-Header', '123'); $response->body('{"status": "ok"}'); $results = $openapi->validate_response($response, { request => $request }); say $results; say ''; # newline say JSON::MaybeXS->new(convert_blessed => 1, canonical => 1, pretty => 1, indent_length => 2)->encode($results);

prints:

request: '/request/body/hello': got integer, not string '/request/body': not all properties are valid

{ "errors" : [ { "absoluteKeywordLocation" : "https://example.com/api#/paths/~1foo~1%7Bfoo_id%7D/post/requestBody/content/application~1json/schema/properties/hello/type", "error" : "got integer, not string", "instanceLocation" : "/request/body/hello", "keywordLocation" : "/paths/~1foo~1{foo_id}/post/requestBody/content/application~1json/schema/properties/hello/type" }, { "absoluteKeywordLocation" : "https://example.com/api#/paths/~1foo~1%7Bfoo_id%7D/post/requestBody/content/application~1json/schema/properties", "error" : "not all properties are valid", "instanceLocation" : "/request/body", "keywordLocation" : "/paths/~1foo~1{foo_id}/post/requestBody/content/application~1json/schema/properties" } ], "valid" : false }

response: valid

{ "valid" : true }

=head1 DESCRIPTION

This module provides various tools for working with an L<OpenAPI Specification v3.1 document|https://spec.openapis.org/oas/v3.1.0#openapi-document> within your application. The JSON Schema evaluator is fully specification-compliant; the OpenAPI evaluator aims to be but some features are not yet available. My belief is that missing features are better than features that seem to work but actually cut corners for simplicity.

=for Pod::Coverage BUILDARGS THAW

=for stopwords schemas jsonSchemaDialect metaschema subschema perlish operationId openapi Mojolicious

=head1 CONSTRUCTOR ARGUMENTS

If construction of the object is not successful, for example the document has a syntax error, the call to C<new()> will throw an exception. Be careful about examining this exception, for it might be a L object, which has a boolean overload of false when it contains errors! But you never do C<if ($@) { ... }>, right?

=head2 openapi_uri

The URI that identifies the OpenAPI document. Ignored if L is provided.

It is used at runtime as the base for absolute URIs used in L objects, along with the request's C header and scheme (e.g. C), when available.

=head2 openapi_schema

The data structure describing the OpenAPI v3.1 document (as specified at Lhttps://spec.openapis.org/oas/v3.1.0). Ignored if L is provided.

=head2 openapi_document

The L document that holds the OpenAPI information to be used for validation. If it is not provided to the constructor, then both L and L B be provided, and L will also be used if provided.

=head2 evaluator

The L object to use for all URI resolution and JSON Schema evaluation. Ignored if L is provided. Optional.

=head1 ACCESSORS/METHODS

=head2 openapi_uri

The URI that identifies the OpenAPI document.

=head2 openapi_schema

The data structure describing the OpenAPI document. See L<the specification/https://spec.openapis.org/oas/v3.1.0>.

=head2 openapi_document

The L document that holds the OpenAPI information to be used for validation.

=head2 document_get

my $parameter_data = $openapi->document_get('/paths/~1foo~1{foo_id}/get/parameters/0');

Fetches the subschema at the provided JSON pointer. Proxies to L<JSON::Schema::Modern::Document::OpenAPI/get>. This is not recursive (does not follow C<$ref> chains) -- for that, use C<< $openapi->recursive_get(Mojo::URL->new->fragment($json_pointer)) >>, see L.

=head2 evaluator

The L object to use for all URI resolution and JSON Schema evaluation.

=head2 validate_request

$result = $openapi->validate_request( $request,

optional second argument can contain any combination of:

my $options = {
  path_template => '/foo/{arg1}/bar/{arg2}',
  operation_id => 'my_operation_id',
  path_captures => { arg1 => 1, arg2 => 2 },
  method => 'get',
},

);

Validates an L, L, L or L object against the corresponding OpenAPI v3.1 document, returning a L object.

Absolute URIs in the result object are constructed by resolving the openapi document path against the L, as well as the C header of the request if a host component is not included in the L.

The second argument is an optional hashref that contains extra information about the request, corresponding to the values expected by L below. It is populated with some information about the request: save it and pass it to a later L (corresponding to a response for this request) to improve performance.

=head2 validate_response

$result = $openapi->validate_response( $response, { path_template => '/foo/{arg1}/bar/{arg2}', request => $request, }, );

Validates an L, L, L or L object against the corresponding OpenAPI v3.1 document, returning a L object.

Absolute URIs in the result object are constructed by resolving the openapi document path against the L, as well as the C header of the request if the request is provided and if a host component is not included in the L.

The second argument is an optional hashref that contains extra information about the request corresponding to the response, as in L.

C is also accepted as a key in the hashref, representing the original request object that corresponds to this response (as not all HTTP libraries link to the request in the response object).

=head2 find_path

$result = $self->find_path($options);

Uses information in the request to determine the relevant parts of the OpenAPI specification. C should be provided if available, but additional data can be used instead (which is populated by earlier L or L calls to the same request).

The single argument is a hashref that contains information about the request. Possible values include:

=over 4

=item *

C: the object representing the HTTP request. Should be provided when available.

=item *

C: a string representing the request URI, with placeholders in braces (e.g. C</pets/{petId}>); see Lhttps://spec.openapis.org/oas/v3.1.0#paths-object.

=item *

C: a string corresponding to the L<operationId|https://learn.openapis.org/specification/paths.html#the-endpoints-list> at a particular path-template and HTTP location under C

=item *

C: a hashref mapping placeholders in the path to their actual values in the request URI

=item *

C: the HTTP method used by the request (used case-insensitively)

=back

All of these values are optional (unless C is omitted), and will be derived from the request URI as needed (albeit less efficiently than if they were provided). All passed-in values MUST be consistent with each other and the request URI.

When successful, the options hash will be populated with keys C, C, C, and C, and the return value is true. When not successful, the options hash will be populated with key C, an arrayref containing a L object, and the return value is false. Other values may also be populated if they can be successfully calculated.

In addition, these values are populated in the options hash (when available):

=over 4

=item *

C: a URI indicating the document location of the operation object for the request, after following any references (usually something under C</paths/>, but may be in another document). Use C<< $openapi->evaluator->get($uri) >> to fetch this content (see L<JSON::Schema::Modern/get>). Note that this is the same as C<< $openapi->recursive_get(Mojo::URL->new->fragment(JSON::Schema::Modern::Utilities::jsonp('/paths', $options->{path_template}{$options->{method}}))) >>. (See the documentation for an operation at Lhttps://learn.openapis.org/specification/paths.html#the-endpoints-list or in the specification at L<§4.8.10 of the specification|https://spec.openapis.org/oas/v3.1.0#operation-object>.)

=item *

C (not necessarily what was passed in: this is always a L)

=back

You can find the associated operation object by using either C, or by calling C<< $openapi->openapi_document->get_operationId_path($operation_id) >> (see L<JSON::Schema::Modern::Document::OpenAPI/get_operationId_path>) (note that the latter will be removed in a subsequent release, in order to support operations existing in other documents).

Note that the L<C|https://spec.openapis.org/oas/v3.1.0#server-object> section of the OpenAPI document is not used for path matching at this time, for either scheme and host matching nor path prefixes. For now, if you use a path prefix in C entries you will need to add this to the path templates under /paths.

=head2 recursive_get

Given a uri or uri-reference, get the definition at that location, following any C<$ref>s along the way. Include the expected definition type (one of C, C, C, C, C, C

# add custom format validations, media types and encodings here
$openapi->evaluator->add_media_type(...);

return $openapi;