Laravel Swagger Package. Generator API Documentation in Swagger format.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
config Update documentation. Aug 2, 2017
resources Clean up. Aug 2, 2017
src Add container to form requests. Jul 12, 2018
tests
.gitignore Fix the tests Mar 15, 2017
.php_cs.dist Allow implicit operations with SwaggerPhp annotations Jan 8, 2017
.styleci.yml Fix CS Jul 30, 2016
.travis.yml Remove Symfony 4 flag from travis. Aug 2, 2017
CONTRIBUTING.md
LICENSE Update license. Aug 2, 2017
README.md Update badges. Aug 2, 2017
UPGRADE-3.0.md Typo Jun 2, 2017
composer.json
phpunit Use phpunit 6 May 31, 2017
phpunit.xml.dist Fix symfony 4 support Jun 14, 2017
update-js.sh Include map files Jun 22, 2017

README.md

Lara Swag

Build Status Total Downloads Latest Stable Version

The LaraSwag package allows you to generate a decent documentation for your APIs.

Installation

First, open a command console, enter your project directory and execute the following command to download the latest version of this bundle (still in beta, for a stable version look here):

composer require zquintana/lara-swag dev-master

Then add the service provider to your app config:

ZQuintana\LaraSwag\Provider\LaraSwagProvider::class

To install the vendor assets like configurations and templates run:

$ php artisan vendor:publish --provider="ZQuintana\LaraSwag\Provider\LaraSwagProvider::class"

To browse your documentation with Swagger UI, register the routes in config/routing/lara_swag.php. To make this easier after you run the vendor:publish command you can add the following to your routes config file:

<?php
...
Route::group(['prefix' => 'api'], function () {
    require_once('lara_swag.php'); // use routes/lara_swag.php if you're using Laravel pre 5.3
});

What does this bundle?

It generates you a swagger documentation from your Laravel app thanks to Describers. Each of these Describers extract infos from various sources. For instance, one extract data from SwaggerPHP annotations, one from your routes, etc.

If you configured the routes above, you can browse your documentation at http://example.org/api/docs.

Use the bundle

You can configure globally your documentation in the config (take a look at the Swagger specification to know the fields available):

<?php

return [
    'documentation' => [
        'info' => [
            'title'       => 'My App',
            'description' => 'This is an awesome app!',
            'version'     => '1.0.0',            
        ]    
    ],
];

To document your routes, you can use annotations in your controllers:


namespace App\Controllers;

use App\Models\User;
use App\Models\Reward;
use ZQuintana\LaraSwag\Annotation\Model;
use Swagger\Annotations as SWG;

class UserController
{
    /*
     * @SWG\Response(
     *     response=200,
     *     description="Returns the rewards of an user",
     *     @SWG\Schema(
     *         type="array",
     *         @Model(type=Reward::class, groups={"full"})
     *     )
     * )
     * @SWG\Parameter(
     *     name="order",
     *     in="query",
     *     type="string",
     *     description="The field used to order rewards"
     * )
     * @SWG\Tag(name="rewards")
     */
    public function fetchUserRewardsAction(User $user)
    {
        // ...
    }
}

What's supported?

This package supports Laravel route requirements, PHP annotations, Swagger-Php annotations.

It supports models through the @Model annotation.

Contributing

See CONTRIBUTING file.

Running the Tests

Install the Composer dependencies:

git clone https://github.com/zquintana/LaraSwag.git
cd LaraSwag
composer install

Then run the test suite:

./phpunit

License

This bundle is released under the MIT license.