The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
JSON-Schema-Modern-Document-OpenAPI-0.006
River stage zero No dependents
1 ++
/ OpenAPI::Modern

NAME

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

VERSION

version 0.006

SYNOPSIS

  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

DESCRIPTION

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.

CONSTRUCTOR ARGUMENTS

openapi_uri

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

openapi_schema

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.

openapi_document

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.

evaluator

The JSON::Schema::Modern object to use for all URI resolution and JSON Schema evaluation. Ignored if "openapi_document" is provided. Optional.

ACCESSORS/METHODS

openapi_uri

The URI that identifies the OpenAPI document.

openapi_schema

The data structure describing the OpenAPI document. See "https://spec.openapis.org/oas/v3.1.0" in the specification.

openapi_document

The JSON::Schema::Modern::Document::OpenAPI document that holds the OpenAPI information to be used for validation.

evaluator

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

validate_request

  $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_captures: a hashref mapping placeholders in the path to their actual values in the request URI

More options will be added later, providing more flexible matching of the document to the request.

validate_response

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

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

More options will be added later, providing more flexible matching of the document to the request.

load_vocabulary_classes

Loads all vocabulary classes found within the resource index of the JSON Schema evaluator. Useful when deserializing an object from disk (where resource data exists in memory but the corresponding implementations are no longer loaded.

ON THE USE OF JSON SCHEMAS

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).

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).

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.

LIMITATIONS

Only certain permutations of OpenAPI documents are supported at this time:

  • for all parameters types, only explode: true is supported

  • for path parameters, only style: simple is supported

  • for query parameters, only style: form is supported

  • 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

SEE ALSO

SUPPORT

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.

You can also find me on the JSON Schema Slack server and OpenAPI Slack server, which are also great resources for finding help.

AUTHOR

Karen Etheridge <ether@cpan.org>

COPYRIGHT AND LICENCE

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.