Download the PHP package hcesrl/laravel-swagger-api without Composer
On this page you can find all versions of the php package hcesrl/laravel-swagger-api. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package laravel-swagger-api
hcesrl/laravel-swagger-api
The packages adds a layer on top of the Laravel routing system allowing you to easily add metadata to your routes in order to create a Swagger UI compliant API.
Table of contents
- Installation
- Basic usage
- Configuration
- HTTPS/Trusted proxies
- Routing
- Route parameters
- Responses
- Advanced configuration
- General route parameters
- Guess parameters from FormRequest
- Tags
- Versions
- Aggregated resources endpoint
- Aggregated models endpoint
- Authorization
- API Json Caching
- Todos
Installation
hc
Install the package:
Publish configuration and assets:
Basic usage
Configuration
The main configuration is located in the config/api.php
file. Here you can set some general metadata for your API
specification such as the title, the description, etc.
Make sure that the prefix
is the same used in your RouteServiceProvider
for the api routes.
HTTPS/Trusted proxies
In case your API is hosted behind a load balancer and does not generate proper secure urls, refer to the Laravel docs about configuring trusted proxies.
Routing
The Api
facade works with the same syntax as the Route
facade and you can use it directly in your
routes/api.php
file.
Note: the supported methods:
get
,post
,put
,delete
,patch
,options
. There's no support for thematch
method because every route must be associated with a single Operation in the Swagger specification.
When you create a new route, the Api facade returns an instance of an Operation object. This object exposes some chainable configuration methods. The following example shows an extensive use of those methods.
Route parameters
You can define different types of route parameters after creating a route through the following methods:
addHeaderParameter
addQueryParameter
addPathParameter
addFormDataParameter
addBodyParameter
All these methods accept 4 parameters: name, description, required and type:
Note: the
addBodyParameter
method doesn't accept atype
parameter, according to the Swagger specification.
If you need a deeper configuration for the parameter, you may pass a Closure function instead of a text description:
Route path parameter auto-parsing
When you define a route containg path parameters using the Laravel syntax, the route URI will be automatically parsed for path parameters, both required and optional.
The route:
will be parsed and the two path parameters will be added automatically. You can still edit the paramaters configuration:
It is also possible to disable the automatic route parsing from the main config file config/api.php
setting
parse_route_parameters
to false
.
Responses
Use the addResponse
to define the route response types:
Advanced configuration
General route parameters
You may need to register different routes using the same parameters (eg. lang or locale) and these could lead to a long and difficult to maintein routes file.
To avoid this you can register general reusable route parameters that will be automatically applied when parameters with the same are found in the route uris.
Guess parameters from FormRequest
In order to simplify the parameters registration, you may bind a Laravel FormRequest directly to a route and let the package guess the parameters from the request rules.
Tags
In order to create a tag for your operations, you may call the tag
method passing the name of the tag and its description, if needed.
You can also pass a callback function to create a group of operations automatically tagged with the given tag.
You may register many tags at once by passing an array to the tags
method:
Versions
If you want to group your routes by different version, you may use the version
method. The grouped routes will be
automatically prefixed and tagged with the given version name.
Aggregated resources endpoint
An aggregate endpoint is an API endpoint that returns a mixed collection of resources, combining both Eloquent models and data generated by Closures.
Note: closures require a non-numeric array key.
Aggregated models endpoint
Building a complex API may require the creation of several endpoints exposing models data. You can easily do this
with the models
shortcut. With this method you can create a general resource endpoints connected to a simple
Resource controller that implements only the index
and show
actions and handles multiple models.
The following configuration:
is equivalent to:
Customize the response
If you use custom API Resources to personalize the API data you can define the following methods within your models in order the provide the right resource to the API server.
Authorization
In order to provide the security definitions for the specification you can use one the following methods:
In any operation you can set the required security schemes via the requiresAuth
method:
and on resources as well:
API Json Caching
To generate a Swagger UI json file cache, just execute the api:cache
Artisan command:
After running this command, your cached json file will be used. Remember, if you add any new routes to the API you will
need to generate a fresh route cache. Because of this, you should only run the api:cache
command during your
project's deployment.
You may use the api:clear
command to clear the API cache:
Todos
- [x] Add support for securityDefinitions;
- [ ] Add support for Components;
- [ ] Add support for response Examples;
- [ ] Implement authentication through Laravel Passport;
License
This package is open-sourced software licensed under the MIT license.
All versions of laravel-swagger-api with dependencies
ext-json Version *
illuminate/contracts Version ^5.5|^6.0|^7.0|^8.0|^9.0
illuminate/filesystem Version ^5.5|^6.0|^7.0|^8.0|^9.0
illuminate/http Version ^5.5|^6.0|^7.0|^8.0|^9.0
illuminate/routing Version ^5.5|^6.0|^7.0|^8.0|^9.0
illuminate/support Version ^5.5|^6.0|^7.0|^8.0|^9.0
calcinai/strut Version ^0.2