Laravel

Install

composer require darkaonline/l5-swagger

Publish the config:

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

Configure

In config/l5-swagger.php, set the scan paths and API info:

'defaults' => [
    'routes' => [
        'api' => 'api/documentation',
        'docs' => 'docs',
        'oauth2_callback' => 'api/oauth2-callback',
        'middleware' => [...],
        'group_options' => [],
    ],

    'paths' => [
        'docs' => storage_path('api-docs'),
        'docs_json' => 'api-docs.json',
        'docs_yaml' => 'api-docs.yaml',
        'annotations' => [
            base_path('app'),
        ],
    ],
],

Add annotations

Add a base annotation to your controller or a dedicated file:

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

Annotate your routes:

/**
 * @OA\Get(
 *     path="/items/{id}",
 *     operationId="getItem",
 *     summary="Get a single item",
 *     tags={"items"},
 *     @OA\Parameter(
 *         name="id",
 *         in="path",
 *         required=true,
 *         @OA\Schema(type="integer")
 *     ),
 *     @OA\Response(
 *         response=200,
 *         description="Item found",
 *         @OA\JsonContent(
 *             @OA\Property(property="id", type="integer"),
 *             @OA\Property(property="name", type="string")
 *         )
 *     )
 * )
 */
public function show(int $id): JsonResponse
{
    return response()->json(['id' => $id, 'name' => 'Widget']);
}

Generate the spec

php artisan l5-swagger:generate

Expose at /openapi.json

Add a route in routes/web.php:

Route::get('/openapi.json', function () {
    return response()->file(storage_path('api-docs/api-docs.json'));
});

The spec is now available at:

http://localhost:8000/openapi.json

Make it publicly accessible

Deploy your app or use a tunnel for local testing:

ngrok http 8000
# then use: https://<random>.ngrok.io/openapi.json

Verify

Visit /openapi.json in your browser. You should see a valid OpenAPI JSON document.

Paste this URL into Automiel’s import step.