Generate a PHP Client API (PSR7 compatible) given a OpenApi (Swagger) specification.
The generated code may contain bug or incorrect behavior, use it as a base for your application but you should never trust it as is.
# jane-openapi [schema-path] [namespace] [destination]
php vendor/bin/jane-openapi generate swagger.json Name\\Space src/Name/Space
This will generate, in the src/Name/Space
, a Resource, a Model and a Normalizer directory from the swagger.json file:
- Resource directory will contain all differents resources of the API with their endpoints;
- Model directory will contain all Model used in the API;
- Normalizer directory will contain a normalizer service class for each of the model class generated.
Since 1.3 you can now use a config file for generating your library, this avoid remember the same options each time and track change over the generation configuration.
For that you need to create a .jane-openapi
at the root of your repository (you can also use a different name but you
will need to indicate the location of this file to the generate command):
<?php
return [
'openapi-file' => __DIR__ . '/swagger.json', // Location of our OpenAPI Specification
'namespace' => 'Namespace\Prefix', // namespace of the generated code
'directory' => __DIR__ . '/src/Namespace/Prefix', // directory where the code will be output
'date-format' => \DateTime::RFC3339, // format of the date that your use (you should not set it unless you have to deal with a non compliant specification)
'reference' => true, // Add the JSON Reference specification to the generated library (so data on the API can use reference like described in https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03)
];
See USAGE documentation for a more complete tutorial.
The Docker PHP library has been built on this, you can see there a complete example of using this library.
Use composer for installation
composer require jane/open-api
Here is a recommended workflow when dealing with the generated code:
- Start from a clean revision on your project (no modified files);
- Update your OpenApi (Swagger) Schema file (edit or download new version);
- Generate the new code;
- Check the generated code with a diff tool:
git diff
for example; - If all is well commit modifications.
An optional and recommanded practice is to separate the generated code in a specific directory
like creating a generated
directory in your project and using jane inside. This allows other developers
to be aware that this part of the project is generated and must not be updated manually.
Here is a quick presentation on how this library transforms a Json Schema file into models and normalizers:
- First step is to read and parse the OpenApi (Swagger) Schema file;
- Second step is to guess api calls, classes and their associated properties and types;
- Once all things are guessed, they are transformed into an AST (by using the PHP-Parser library from nikic);
- Then the AST is written into PHP files.
- Optionally, if php-cs-fixer is present, it is used to format the generated code
Open Source time sponsored by JoliCode
View the LICENSE file attach to this project.