Laravel Swagger Integration

Our project at work has installed the L5-Swagger to document our API routes. The first thing to note is that documentation is scattered, the README of the project states:

This package is a wrapper of swagger-php and swagger-ui adapted to work with Laravel.

Installation and initial configuration are easy enough, but connecting to your authentication scheme is a bit more challenging.

There is a wiki on Using-Swagger-UI-with-Passport, but this seems like an easy automatic way to create tokens, instead of using the built in methods of the passport library.

config/l5-swagger.php has a scheme for our chosen auth defined in defaults.securityDefinitions.securitySchemes.passport.

This tutorial fills in some gaps, but raises questions for me as well. At the very least it gives us an example of how to tie auth to an endpoint.

/**
 * @OA\Get(
 *      path="/v1/user",
 *      tags={"User"},
 *      security={
 *          {"passport": {}},
 *      },
 *      @OA\Response(response="200", description="An example resource")
 * )
*/

Next issue was figuring out how to support documenting multiple versions of the API simultaneously. Going by this pull request, apparently you can do so by defining multiple objects in the documentations section of l5-swagger.php (default is already defined). Each object will be merged with the values of the defaults section to build a final config array.

'documentations' => [
    'v1' => [
        'routes' => [
            /*
             * Route for accessing api documentation interface
            */
            'api' => 'api/v1/documentation',
        ],
        'paths' => [
            /*
             * Absolute paths to directory containing the swagger annotations are stored.
            */
            'annotations' => [
                base_path('app'),
            ],

        ],
        'scanOptions' => [
            'exclude' => [
                base_path('app/Http/Controllers/Api/V2')
            ]
        ]
    ],
    'v2' => [
        'routes' => [
            /*
             * Route for accessing api documentation interface
            */
            'api' => 'api/v2/documentation',
        ],
        'paths' => [
            /*
             * Absolute paths to directory containing the swagger annotations are stored.
            */
            'annotations' => [
                base_path('app'),
            ],

        ],
        'scanOptions' => [
            'exclude' => [
                base_path('app/Http/Controllers/Api/V1')
            ]
        ]
    ]
]

Since both versions occupy the /app directory we have to exclude some of the files during successive runs so that there is no conflicts. To avoid confusion between different versions of the API you need to define the @OA\Info tag in a different controller, and exclude all the other files that do not share this version. Each versioned controller should define a @OA\Info tag like:

namespace App\Http\Controllers\Api\V1;

/**
 * @OA\Info(
 *   title="Laravel API",
 *   version="1.0.0"
 * )
 */

class Controller
{
}