Download the PHP package kevupton/laravel-swagger without Composer

laravel-swagger

Swagger Annotations Generator for Laravel 5.0 and up.

Introduction

This package uses the Swagger PHP library and Laravel to generate an OpenAPI 3.0-compliant JSON Specification.

This package supports Laravel 5.0 and above.

Installation

Table Of Contents

• Models
• Controllers
• Custom Handlers
• Overriding Values
• Seperate Container Class

Models

Usage

\Kevupton\LaravelSwagger\scan($path, $models);

Define your Eloquent Models as shown below, in order for laravel-swagger to include in your specification:

Example model:

Output

Controllers

Laravel-Swagger allows you to define a generic, customized output for each Controller. It requires a parent controller to define the base of each output response.

Getting Started

For example, you have controllers TestController, FooController and BarController which serves API requests.

Each of the index methods share similar functionality, which is to display a list of results with pagination. The router definition is as follows:

Example Router Definition

I have a custom package to help with Controller functionality which can be found at Ethereal's Resource Trait

Since these Controllers share the same basic output, you can utilize a BaseController that the above Controllers may inherit from. An example BaseController is shown below:

Example Base Controller

getSwaggerRoutes is a method that defines the template structure of the specification for the above mentioned Controllers.

You would have noticed, that there are placeholder values, such as {{response}}, included in the above definition. These values will be replaced with the values found on each of the child Controllers. Refer to the section on keys.

Route Matching

Referring to the routing definition as shown here, the key index refers to the route key index of the above Router definitions.

For example, referring to the above, the router key index defined in getSwaggerRoutes will apply to the route v1.bar.index , and not v1.bar.show.

Likewise, v1.test.index will match the above definition, but not v1.index.test.

Keys

{{keyname}} keyname refers to the name of the static variable in your Controller, whose value it will be replaced with.

Referring to the example, you can see the example keys:

The default handler will search the Child Controller for each variable of the same name, and replace the key with the values the variable contains.

Example Child Controller

Example Output

This is one of the paths located in the swagger json output.

NOTE The default handler will replace the key with the static variable of the same name found in your Controller. You may modify this behavior in the section Editing the Default Behaviour.

Custom Handlers

Definition

Should you require to change the default behavior of the default handler, you may extend the handler class, and implement the handle method, as shown below.

To use your new custom handler, you may define getSwaggerHandler, returning the ::class of the new Custom Handler, as shown below.

Example Custom Handler Implementation

Overriding Values

Should your Child Controller contains the definition of a static variable, overriding the parent Controller's values, the Child Controller's values will take effect.

Seperate Container Class

Instead of defining the getSwaggerMethods, getSwaggerRoutes and getSwaggerHandler directly in your parent and child Controllers, you may define them in a separate class.

You may then include it in your BaseController, or any other Controllers, using the static variable $swagger_container. Please refer to the example below.

Example Custom Container Implementation

Example Base Controller Implementation