Jane 5.0 has been released! 🍾

Jane is a set of libraries to generate models & API clients based on OpenApi specs. It will generate everything you need to use your API such as endpoints and related exceptions if needed.

As a reminder, OpenApi Specification is an API description format or API definition language. Basically, an OpenApi Specification allows you to describe an API including (among other things):

• General information about the API
• Available paths (/resources)
• Available operations on each path (get /resources)
• Input/Output for each operation

The previous version of JanePHP was released in February 2018 and used OpenApi 2 specification, async support and our first documentation.

Since that release, Jane’s OpenApi library has been installed more than 40,000 times 🎉.

At JoliCode, we are using Jane in a lot of different projects, to make API communication simpler and to build full API clients, such as: Slack, Docker, Harvest or Forecast.

Section intitulée why-is-jane-5-cooler-than-4Why is Jane 5 cooler than 4? 😎

A year after the previous version, we chose to release Jane 5.0 with two major features:

Section intitulée openapi-3–0–2-supportOpenApi 3.0.2 support 📝

Since Swagger 2.0 (OpenApi is the new name of Swagger), a lot of changes has been made:

• definitions becomes components/schemas;
• Inside endpoint parameters, model definition is now indexed by a schema key;
• Again in endpoint parameters, in: body objects have a new separated field called requestBody;
• Better support for content-type negotiation.

Many other features can be found on OpenApi 3.0 release blog post or the very detailed ReadMe blog post.

Section intitulée psr-18-client-generationPSR-18 Client generation 🛠

PSR-18 is a standard made by PHP-FIG to harmonize HTTP Clients among PHP.

This allows us to use any PSR-18 compatible client (including Symfony’s HttpClient component). With this release it’s preferable to use a PSR-18 Client than HTTPlug.

Section intitulée a-quick-exampleA quick example 🔎

First, you’ll need to require jane-php packages:

composer require --dev jane-php/open-api "^5.0"
composer require jane-php/open-api-runtime "^5.0"

OpenApi package is only needed to generate classes. OpenApiRuntime is needed to use theses classes.

Now, we need to configure Jane before generation. We create a .jane-openapi file:

return [
    'openapi-file' => __DIR__ . '/schema.yaml',
    'namespace' => 'CatFacts\Api',
    'directory' => __DIR__ . '/generated/',
];

It will contain a reference to your main schema file, the PHP namespace you want for generated classes and the directory you want to use. Other configuration can be made in that file, read more in the documentation about it. Also, the schema used here can be found in the documentation with more details.

After that, one line will generate classes based on your schema:

$ vendor/bin/jane-openapi generate

Then you can use them to communicate with your API 🎉

$ tree generated/
generated/
├── Client.php
├── Endpoint
│   └── RandomFact.php
├── Model
│   └── Fact.php
└── Normalizer
    ├── FactNormalizer.php
    └── NormalizerFactory.php

3 directories, 5 files

Section intitulée want-to-go-furtherWant to go further? 🚶

Here is the full working example or read the documentation.

We are using Jane every day and on many projects, we will continue to update and implement more features. If you want to contribute, you can help us by checking issues. If you don’t know how to contribute, you can follow our guide about contributing on Jane and how the library works.