Download the PHP package hcesrl/laravel-swagger-api without Composer

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 the match 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 a type 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.