Example¶
In this section, we will see a working example of OpenApi v3 client onto a simple API that gives facts about cats and comment it.
Warning
We suggest you to read Generating a Client and Using a generated client first to understand this page more easily.
You can find the fully working example on the following link: https://github.com/janephp/openapi3-example
OpenAPI schema¶
First, we need a valid OpenAPI schema. You can use tool such as Stoplight or other OpenApi designer.
I choosed to represent CatFacts API within this example:
openapi: 3.0.0
info:
version: 1.0.0
title: 'CatFacts API'
servers:
- url: https://cat-fact.herokuapp.com
paths:
/facts/random:
get:
operationId: randomFact
responses:
200:
description: 'Get a random `Fact`'
content:
application/json:
schema:
$ref: '#/components/schemas/Fact'
components:
schemas:
Fact:
type: object
properties:
_id:
type: string
description: 'Unique ID for the `Fact`'
__v:
type: integer
description: 'Version number of the `Fact`'
user:
type: string
description: 'ID of the `User` who added the `Fact`'
text:
type: string
description: 'The `Fact` itself'
updatedAt:
type: string
format: date-time
description: 'Date in which `Fact` was last modified'
sendDate:
type: string
description: 'If the `Fact` is meant for one time use, this is the date that it is used'
deleted:
type: boolean
description: 'Weather or not the `Fact` has been deleted (Soft deletes are used)'
source:
type: string
description: 'Can be `user` or `api`, indicates who added the fact to the DB'
used:
type: boolean
description: 'Weather or not the `Fact` has been sent by the CatBot. This value is reset each time every `Fact` is used'
type:
type: string
description: 'Type of animal the `Fact` describes (e.g. ‘cat’, ‘dog’, ‘horse’)'
This schema describe the endpoint and the model of the CatFact API.
Jane configuration¶
We need to configure Jane before generation. So we create a .jane-openapi
file:
<?php
return [
'openapi-file' => __DIR__ . '/schema.yaml',
'namespace' => 'CatFacts\Api',
'directory' => __DIR__ . '/generated/',
'date-format' => \DateTimeInterface::RFC3339_EXTENDED, // date-time format use by CatFact API
'client' => 'psr18',
];
It will contains a reference to your main schema file (that file can be linked to other files if you want), the PHP namespace you want for generated classes and the directory you want to use.
Warning
Client argument is recommended, if you don’t fill it, it will generated a HTTPlug Client which is not what we are showing here and HTTPlug Client generation is deprecated since Jane v5.1.0
Jane generation¶
Now we can run generation, basically just require jane with composer (see OpenAPI for more details about installation) and run the following command:
vendor/bin/jane-openapi generate
It will find any .jane-openapi
file and use it as configuration. If your file has a different name, just add
-c path/to/my/file
after the command.
Creating a client¶
Then you need a Client to bridge between Jane and your application. Jane use PSR18 to make this bridge easier which allow us to have any middleware we need. If you provide server URL in your schema and you have no authentification needed for your API, then everything will be automated by Jane, you just have to do:
use CatFacts\Api\Client;
$client = Client::create();
And that’s all you need. If you need authentification, please read Using a generated client.
Using your client¶
Finally we can use our Client and try to get some cool cat fact:
<?php
require_once __DIR__.'/vendor/autoload.php';
$client = \CatFacts\ClientFactory::create();
$fact = $client->randomFact();
And this will give us a Fact
object as following:
object(CatFacts\Api\Model\Fact)#29 (10) {
["id":protected]=>
string(24) "591f98108dec2e14e3c20b0f"
["v":protected]=>
int(0)
["user":protected]=>
NULL
["text":protected]=>
string(63) "Cats have been domesticated for half as long as dogs have been."
["updatedAt":protected]=>
object(DateTime)#28 (3) {
["date"]=>
string(26) "2019-08-24 20:20:02.145000"
["timezone_type"]=>
int(2)
["timezone"]=>
string(1) "Z"
}
["sendDate":protected]=>
NULL
["deleted":protected]=>
bool(false)
["source":protected]=>
string(3) "api"
["used":protected]=>
bool(false)
["type":protected]=>
string(3) "cat"
}