Disclaimer: This post is a copy of my JoliCode blog post.
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 (
- Available operations on each path (
- 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 🎉.
Why is Jane 5 cooler than 4? 😎
A year after the previous version, we chose to release Jane 5.0 with two major features:
OpenApi 3.0.2 support 📝
Since Swagger 2.0 (OpenApi is the new name of Swagger), a lot of changes has been made:
- Inside endpoint parameters, model definition is now indexed by a
- Again in endpoint parameters,
in: body objects have a new separated field called
- Better support for content-type negotiation.
PSR-18 Client generation 🛠
A 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
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
Want to go further? 🚶
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.