Download the PHP package asseco-voice/laravel-open-api without Composer

On this page you can find all versions of the php package asseco-voice/laravel-open-api. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package laravel-open-api

Laravel OpenApi generator

This package provides painless OpenApi YML generation from existing routes.

The idea is to have as little work to do as possible in order to generate the API documentation, so the package will try to assume a lot of things such as models from controller names, request and response parameter based on actual tables etc.

For custom inputs/outputs, options will be provided.

Installation

Install the package through composer. It is automatically registered as a Laravel service provider.

composer require asseco-voice/laravel-open-api

Usage

Running the command php artisan asseco:open-api will generate a new .yml file at project_root/open-api.yml.

What is covered out-of-the-box:

For cases not covered by this convention, refer to overriding defaults section.

For additional tweaking, refer to config.

Depending on number of routes, first run may take a few seconds as it is requesting a DB schema for each model it can find. This is cached, so every subsequent run will run much faster.

Simple out-of-the-box example

Given the controller:

Overriding defaults

Custom cases are handled through controller and method annotations in doc blocks:

Groups (tags)

When talking about 'groups', we are actually talking about OpenApi 'tags'.

By default, command will take the controller name, remove Controller from it and split PascalCase with spaces (i.e. SysUserController results in Sys User group name).

It is possible to stack multiple group annotations.

Models

Model is used to try to automatically generate inputs and outputs for standard Laravel CRUD functions.

Input (request): model DB schema with either only fillable properties or except guarded. Fillable properties have precedence, guarded will be ignored if fillable exists.

Output (response): complete model DB schema without hidden fields.

It is completely valid to have no model associated. In this case, no automatic actions will be performed which require an existing model class.

By default, model name is extracted from controller name. To change this behavior, you have few options:

Controller tag has higher precedence over configuration mapping. If both exist, and controller tag fails, configuration will try to fetch the model as well. Failing on both fronts will result in model being null.

It is possible to exclude part of the model for the request:

Path parameters

By default, path parameter(s) will be set as integer (assuming most of the path parameters are model IDs). In case you want to use UUIDs, this can be changed in asseco-open-api config file by setting service_uses_uuid to true.

Override them by including the following in the method doc block:

Examples:

It is not possible to set path parameter required property. It is automatically set to true because OpenApi doesn't support optional path parameters (even though Laravel does).

Operation ID

By default, operationId will be generated for each route, based on the controller/HTTP method mapping and the name of the model. If you want to override the default, you can use @operationId to provide a different suffix to the operation ID (which will replace what would be an auto-generated model).

Prepended controller/HTTP method will stay intact because of possible conflicts when using update routes which map to both PUT and PATCH verbs.

Example:

Request/response parameters

By default, request/response parameter(s) will be extracted from model.

Override them by including @request or/and @response in the method doc block.

Example for @request, working the same for @response:

Examples:

For multiple parameters it is also possible to adopt a different convention:

In case you want an arbitrary string as a request/response, it can be achieved by using double quotes when setting request/response parameters. This way, all other parameters will be ignored and only the string inside double quotes will be returned.

Example:

You can include additional input/output models alongside original model with @requestAppend key Class or @responseAppend key Class in your method doc block. This will append given Class properties on already existing model using the key as a key.

I.e. having original model User (with properties name, email) you want to append Post model (with properties title, description) to it as a list of inputs.

This will result in following request:

Response specific

Responses will by default be marked as multiple (indicating collection output, not a single model) when looking at GET request without path parameters.

If the variable type is array, you can provide additional property within the parenthesis (be sure not to leave blank space between type and parenthesis) to indicate of what type are the array values:

It is also possible to directly append a pivot table to the response, even if it has no model associated with it.

For example, if the table was appended to the User model, the following response will be returned:

Cache

Models database schema is being cached for performance (1d TTL), if you modify a migration be sure to run php artisan asseco:open-api --bust-cache which will force re-caching.

Config

Publish the configuration with php artisan vendor:publish --provider="Asseco\OpenApi\OpenApiServiceProvider".

Configuration requires your minimal engagement, however there are some things which package can't assume.


All versions of laravel-open-api with dependencies

PHP Build Version
Package Version
Requires php Version ^8.1
laravel/framework Version ^10.0
symfony/yaml Version ^6.0
mpociot/reflection-docblock Version ^1.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package asseco-voice/laravel-open-api contains the following files

Loading the files please wait ....