🎉 Jane v5.3: Performances, Authentication & OpenAPI 2!

Disclaimer: This post is a copy of my JoliCode blog post.

Two months after v5.2 and four months after v5.0, we are releasing v5.3 with focus on three things:

Performance

Before, generating a really big OpenAPI schema was very long. We even had issues where the generation took more than 40 minutes! Thanks to @lyrixx & @bastnic who took time to dig into Jane’s generation process and turned those 40 minutes into just 20 seconds!

We also deprecated the NormalizerFactory replaced by JaneObjectNormalizer which will load needed Normalizers only when needed. This change can have a really huge impact on schemas with a lot of models (In the related PR, with 509 Normalizers we go from 57ms to 3.5ms during class autoload).

You can see more details into the related PR: - GH#197 Local cache for Reference contents; - GH#210 Added JaneObjectNormalizer to lazy-load Normalizer when needed; - GH#227 Fixing JSON Pointer being created too much time.

Authentication support

OpenAPI has a securitySchemes field to describe authentication and authorization schemes. With v5.3 we introduced support for authentication types http & apiKey (oauth2 is a bit harder to implement, but we’re open to contribution if you want to give it a try!).

In your schema, you’ll have the following description:

securityDefinitions:
  Bearer:
    type: http
    scheme: Bearer
  ApiKey:
    type: apiKey
    in: query
    name: api_key

Jane will now generate: - BearerAuthentication for Bearer scheme which will inject a given token in an HTTP Header (see: related example); - ApiKeyAuthentication for ApiKey scheme which will inject a api_key query parameter with your token to all requests (see: related example).

And to use them, you have to do the following:

$httpClient = new Psr18Client();
// setup your HttpClient ...

$client = Client::create($httpClient, new BearerAuthentication('token')); // with Bearer auth
$client = Client::create($httpClient, new ApiKeyAuthentication('apiKey')); // with ApiKey auth

And after that, all your requests will be authenticated! 🔓🎉

Next step is to support authentication scopes on Jane generated endpoints to allow you to have multiple security schemes and Jane choose the right one to use!

OpenAPI 2 backport

Before v5.3, OpenAPI 2 was only supported on the v4.x branch and it was such a pain to maintain. To make it easier to maintain and to use, we moved the component to the master branch as open-api-2 component! We even splitted all features that are in common with OpenAPI 3 to allow OpenAPI 2 to take advantage of OpenAPI 3 enhancements at no cost (including performance & Authentication support 😉).

Here is a diff to show the related changes you have to do in your composer.json:

    "require": {
-        "jane-php/open-api-runtime": "^4",
+        "jane-php/open-api-runtime": "^5",
    },
    "require-dev": {
-        "jane-php/open-api": "^4",
+        "jane-php/open-api-2": "^5",
    },

As a result of this change, jane-php/open-api component is now deprecated and should be replaced by jane-php/open-api-3, on our next major version (v6) it will be removed. And the v4.x and all related tags are also deprecated and should be replaced by jane-php/open-api-2 component.

Here is a diff to show the related changes you have to do in your composer.json:

    "require-dev": {
-        "jane-php/open-api": "^5",
+        "jane-php/open-api-3": "^5",
    },

–

We also had other fixes and improvements, you can see the complete list on the v5.3 release page.

Feel free to try it out and if you have any questions, our repository issues are open: https://github.com/janephp/janephp/issues