Swaggervel (Swagger PHP and Swagger UI in Laravel)

Introduction

The [Swaggervel] "package combines swagger-php and swagger-ui into one Laravel-friendly package" - https://github.com/slampenny/Swaggervel.

Swagger allows you to create API documentation like this (taken from swagger-ui pet store example here):

Swagger-php is used for annotating PHP code and creating JSON that can be used by swagger-ui to generate HTML documentation.

Installation

composer.json

"jlapp/swaggervel": "1.0.*@dev"

Add Jlapp\Swaggervel\SwaggervelServiceProvider to your providers array in app/config/app.php above your routes provider (to avoid catch all routes).

Run php artisan vendor:publish to push config files to your app folder.

Running

http[s]://your-api-endpoint.com/api-docs

http[s]/your-api-endpoint.com/docs

You can see your changes on page load if generateAlways is set to true in app/config/packages/jlapp/swaggervel/app.php . In production you will want to turn this option off in your local configuration. If you want to manually generate the documentation then run swagger on your code:

./vendor/bin/swagger app/ -o app/storage/docs/

Controller Annotation

use Swagger\Annotations as SWG; /** * @SWG\Resource( * apiVersion="1.0", * resourcePath="/animal", * description="Animal operations", * produces="['application/json']" * ) */ class AnimalController extends \BaseController { /** * @SWG\Api( * path="/animals", * @SWG\Operation( * method="GET", * summary="Fetch animals" * ) * ) */ public function index() { // index code } /** * @SWG\Api( * path="/animal/{animal_id}", * @SWG\Operation( * method="GET", * summary="Displays an animal", * @SWG\Parameter( * name="animal_id", * description="id of animal to fetch", * paramType="path", * required=true, * allowMultiple=false, * type="integer" * ), * @SWG\ResponseMessage(code=404, message="Animal not found") * ) * ) */ public function show() { // show code } }

@SWG\Resource

@SWG\Api

@SWG\Operation

@SWG\Parameter

@SWG\ResponseMessage

- @SWG\Resource - @SWG\Api - @SWG\Operation - @SWG\Parameter - @SWG\ResponseMessage

Model Annotation

use Swagger\Annotations as SWG; /** * @SWG\Model( * id="Animal", * @SWG\Property(name="id", type="integer", required=true), * @SWG\Property(name="slug", type="string", required=true), * @SWG\Property(name="name", type="string", required=true), * @SWG\Property(name="carnivore", type="boolean", required=false), * @SWG\Property(name="obligate_carnivore", type="boolean", required=false), * ... * ... * ) */ class Animal extends Eloquent implements AnimalInterface { // model implementation }

type

/** * @SWG\Api( * path="/animal/{animal_id}", * @SWG\Operation( * method="GET", * summary="Displays an animal", * type="Animal", * @SWG\Parameter( * name="animal_id", * description="id of animal to fetch", * paramType="path", * required=true, * allowMultiple=false, * type="integer" * ), * @SWG\ResponseMessage(code=404, message="Animal not found") * ) * ) */ public function show() { // show code }

This will show a Model link in Swagger UI so API consumers can understand what an Animal looks like.

Learn more about annotations here.

Tips

If you are running swagger from the command-line, ensure you parse both your models and controllers so you can see the models in the UI. I.e. ./vendor/bin/swagger app/ -o app/storage/docs/ not ./vendor/bin/swagger app/models -o app/storage/docs/ and not ./vendor/bin/swagger app/controllers -o app/storage/docs/ .

Final notes