OpenAPI::Client - A client for talking to an Open API powered server
OpenAPI::Client can generating classes that can talk to an Open API server. This is done by generating a custom class, based on a Open API specification, with methods that transform parameters into a HTTP request.
The generated class will perform input validation, so invalid data won't be sent to the server.
Note that this implementation is currently EXPERIMENTAL, but unlikely to change! Feedback is appreciated.
The specification given to "new" need to point to a valid OpenAPI document, in either JSON or YAML format. Example:
--- swagger: 2.0 host: api.example.com basePath: /api schemes: [ "http" ] paths: /foo: get: operationId: listPets parameters: - name: limit in: query type: integer responses: 200: { ... }
host, basePath and the first item in schemes will be used to construct "base_url". This can be altered at any time, if you need to send data to a custom endpoint.
host
basePath
schemes
The OpenAPI API specification will be used to generate a sub-class of OpenAPI::Client where the "operationId", inside of each path definition, is used to generate methods:
use OpenAPI::Client; $client = OpenAPI::Client->new("file:///path/to/api.json"); # Blocking $tx = $client->listPets; # Non-blocking $client = $client->listPets(sub { my ($client, $tx) = @_; }); # With parameters $tx = $client->listPets({limit => 10});
If you want to request a different server than what is specified in the Open API document:
$client->base_url->host("other.server.com");
$base_url = $self->base_url;
Returns a Mojo::URL object with the base URL to the API. The default value comes from schemes, basePath and host in the Open API specification.
$code = $self->pre_processor; $self = $self->pre_processor(sub { my ($headers, $req) = @_; ... });
Holds a code ref that can pre-process the request. The return values are passed on to "build_tx" in Mojo::UserAgent. Example:
$self->pre_processor(sub { my ($headers, $req) = @_; return $headers, json => {whatever => 42}; });
The code above will result in this:
$self->ua->build_tx($http_method, $url, $headers, json => {whatever => 42}); ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
$headers is a hash-ref containing the request headers and $req is a hash-ref that can contain either the key "body" or "form". Note that additional parameters might be added to $req, though it is unlikely.
$headers
$req
$ua = $self->ua;
Returns a Mojo::UserAgent object which is used to execute requests.
$tx = $self->call($operationId => @args); $self = $self->call($operationId => @args, sub { my ($self, $tx) = @_; });
Used to either call an $operationId that has an "invalid name", such as "list pets" instead of "listPets" or to call an $operationId that you are unsure is supported yet. If it is not, an exception will be thrown, matching text "No such operationId".
$operationId
$promise = $self->call_p($operationId => @args); $promise->then(sub { my ($self, $tx) = @_; });
As "call" above, but instead of returning a $tx, returns a Mojo::Promise of that $tx. Obviously, you should not give a callback.
$tx
$client = OpenAPI::Client->new($specification, \%attributes); $client = OpenAPI::Client->new($specification, %attributes);
Returns an object of a generated class, with methods generated from the Open API specification located at $specification. See "schema" in JSON::Validator for valid versions of $specification.
$specification
Note that the class is cached by perl, so loading a new specification from the same URL will not generate a new class.
Extra %attributes:
%attributes
app
Specifying an app is useful when running against a local Mojolicious instance.
coerce
See "coerce" in JSON::Validator. Default to 1.
$validator = $self->validator; $validator = $class->validator;
Returns a JSON::Validator::OpenAPI::Mojolicious object for a generated class. Not that this is a global variable, so changing the object will affect all instances.
Copyright (C) 2017, Jan Henning Thorsen
This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.
Jan Henning Thorsen - jhthorsen@cpan.org
jhthorsen@cpan.org
Ed J - etj@cpan.org
etj@cpan.org
To install OpenAPI::Client, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OpenAPI::Client
CPAN shell
perl -MCPAN -e shell install OpenAPI::Client
For more information on module installation, please visit the detailed CPAN module installation guide.