OpenAPI::Modern - Validate HTTP requests and responses against an OpenAPI document
version 0.005
my $openapi = OpenAPI::Modern->new( openapi_uri => 'openapi.yaml', 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: 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 = HTTP::Request->new( POST => 'http://example.com/foo/bar', [ 'My-Request-Header' => '123', 'Content-Type' => 'application/json' ], '{"hello": 123}', ); say $openapi->validate_request($request, { path_template => '/foo/{foo_id}', path_captures => { foo_id => 'bar' }, }); say 'response:'; my $response = HTTP::Response->new( 200 => 'OK', [ 'My-Response-Header' => '123' ], '{"status": "ok"}', ); say $openapi->validate_response($response, '/foo/{foo_id}');
prints:
request: '/request/body/hello': wrong type (expected string) '/request/body': not all properties are valid response: valid
This module provides various tools for working with an OpenAPI Specification v3.1 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.
The URI that identifies the OpenAPI document. Ignored if "openapi_document" is provided.
The data structure describing the OpenAPI v3.1 document (as specified at https://spec.openapis.org/oas/v3.1.0). Ignored if "openapi_document" is provided.
The JSON::Schema::Modern::Document::OpenAPI document that holds the OpenAPI information to be used for validation. If it is not provided to the constructor, then "openapi_uri" and "openapi_schema" MUST be provided, and "evaluator" will also be used if provided.
The JSON::Schema::Modern object to use for all URI resolution and JSON Schema evaluation. Ignored if "openapi_document" is provided. Optional.
The URI that identifies the OpenAPI document.
The data structure describing the OpenAPI document. See "https://spec.openapis.org/oas/v3.1.0" in the specification.
The JSON::Schema::Modern::Document::OpenAPI document that holds the OpenAPI information to be used for validation.
The JSON::Schema::Modern object to use for all URI resolution and JSON Schema evaluation.
$result = $openapi->validate_request( $request, { path_captures => { arg1 => 1, arg2 => 2 }, path_template => '/foo/{arg1}/bar/{arg2}', }, );
Validates an HTTP::Request object against the corresponding OpenAPI v3.1 document, returning a JSON::Schema::Modern::Result object.
The second argument is a hashref that contains extra information about the request. Possible values include:
path_template: a string representing the request URI, with placeholders in braces (e.g. /pets/{petId}); see https://spec.openapis.org/oas/v3.1.0#paths-object.
path_template
/pets/{petId}
path_captures: a hashref mapping placeholders in the path to their actual values in the request URI
path_captures
More options will be added later, providing more flexible matching of the document to the request.
$result = $openapi->validate_response( $response, { path_template => '/foo/{arg1}/bar/{arg2}', }, );
Embedded JSON Schemas, through the use of the schema keyword, are fully draft2020-12-compliant, as per the spec, and implemented with JSON::Schema::Modern. Unless overridden with the use of the jsonSchemaDialect keyword, their metaschema is https://spec.openapis.org/oas/3.1/dialect/base, which allows for use of the OpenAPI-specific keywords (discriminator, xml, externalDocs, and example), as defined in "https://spec.openapis.org/oas/v3.1.0#schema-object" in the specification. Format validation is turned on, and the use of content* keywords is off (see "validate_content_schemas" in JSON::Schema::Modern).
schema
discriminator
xml
externalDocs
example
References (with the $ref) keyword may reference any position within the entire OpenAPI document; as such, json pointers are relative to the root of the document, not the root of the subschema itself. References to other documents are also permitted, provided those documents have been loaded into the evaluator in advance (see "add_schema" in JSON::Schema::Modern).
$ref
Values are generally treated as strings for the purpose of schema evaluation. However, if the top level of the schema contains "type": "number" or "type": "integer", then the value will be (attempted to be) coerced into a number before being passed to the JSON Schema evaluator. Type coercion will not be done if the type keyword is omitted. This lets you use numeric keywords such as maximum and multipleOf in your schemas. It also resolves inconsistencies that can arise when request and response objects are created manually in a test environment (as opposed to being parsed from incoming network traffic) and can therefore inadvertently contain perlish numbers rather than strings.
"type": "number"
"type": "integer"
type
maximum
multipleOf
Only certain permutations of OpenAPI documents are supported at this time:
for all parameters types, only explode: true is supported
explode: true
for path parameters, only style: simple is supported
style: simple
for query parameters, only style: form is supported
style: form
for header parameters, only style: simple is supported
cookie parameters are not checked at all yet
for query and header parameters, only the first value of each name is considered
media-type encodings in parameters are not yet supported
JSON::Schema::Modern::Document::OpenAPI
JSON::Schema::Modern
https://json-schema.org
https://www.openapis.org/
https://oai.github.io/Documentation/
https://spec.openapis.org/oas/v3.1.0
Bugs may be submitted through https://github.com/karenetheridge/JSON-Schema-Modern-Document-OpenAPI/issues.
I am also usually active on irc, as 'ether' at irc.perl.org and irc.libera.chat.
irc.perl.org
irc.libera.chat
You can also find me on the JSON Schema Slack server and OpenAPI Slack server, which are also great resources for finding help.
Karen Etheridge <ether@cpan.org>
This software is copyright (c) 2021 by Karen Etheridge.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install JSON::Schema::Modern::Document::OpenAPI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm JSON::Schema::Modern::Document::OpenAPI
CPAN shell
perl -MCPAN -e shell install JSON::Schema::Modern::Document::OpenAPI
For more information on module installation, please visit the detailed CPAN module installation guide.