Swagger Laravel Autogenerate

Overview

Composer package g4t/swagger registers a service provider that exposes a Swagger UI page and a JSON OpenAPI endpoint. The spec is built from registered application routes (URI, HTTP methods, middleware, tags) and can incorporate FormRequest rules for request schemas and parameters.

Optional features include inferred response examples from controllers, error/validation examples, per-route documentation helpers, basic auth for the UI, cached static JSON for faster responses, and an experimental mock-server workflow.

Package statistics

Live numbers from the Packagist package JSON for g4t/swagger (installs, GitHub signals, and favorites).

Features

• OpenAPI 3.x JSON from registered routes
• FormRequest rules drive request schemas and query/path parameters where applicable
• Optional inferred success responses (infer_response_examples): literals, JsonResource, response()->json(...), and more
• Optional inferred errors (infer_error_response_examples): JSON with status, abort(), validation-style 422 when rules warrant it
• storage/swagger/… JSON overrides for per-route response examples when enabled
• Faster JSON: when not in static-only mode, serve public/{cached_spec_path} if present (use_cached_spec_when_present)
• Route macros: ->description(), ->summary(), ->hiddenDoc()
• Controller attribute: #[SwaggerSection('…')]
• Optional basic authentication for the documentation UI
• Commands: swagger:cache, make:swagger, experimental swagger:mock-server

Installation

Require the package with Composer:

composer require g4t/swagger

Laravel will auto-discover G4T\Swagger\SwaggerServiceProvider via composer.json extra configuration.

Publish configuration

php artisan vendor:publish --provider "G4T\Swagger\SwaggerServiceProvider"

Edit config/swagger.php for titles, URL prefix, versions, inference flags, cache path, auth, and servers.

Usage

Video walkthrough

Watch on YouTube — how to use the package in a Laravel app.

1. Publish config/swagger.php (see Installation).
2. Adjust title, URL prefix, versions, inference flags, cached_spec_path / use_cached_spec_when_present, etc.
3. Open the UI at /{swagger.url} (default: /swagger/documentation), e.g. https://your-app.test/swagger/documentation.
4. The issues page is at swagger.issues_url (default: /swagger/issues).

Route description

Route::get('user', [UserController::class, 'index'])
    ->description('Get list of users with pagination.');

Short summary

Route::get('user', [UserController::class, 'index'])
    ->summary('get users.');

Hide from docs

Route::get('user', [UserController::class, 'index'])->hiddenDoc();

Controller section (OpenAPI tag grouping)

<?php

namespace App\Http\Controllers;

use G4T\Swagger\Attributes\SwaggerSection;

#[SwaggerSection('everything about your users')]
class UserController extends Controller
{
    // ...
}

Documentation basic auth

In config/swagger.php:

"enable_auth" => false,
"username" => "admin",
"password" => "pass",
"sesson_ttl" => 100000,

Set enable_auth to true in production if you need to protect the UI.

Documentation routes

Routes are registered under the configured paths (defaults shown):

All of the above run behind BasicAuthentication middleware when auth is enabled in config.

Artisan commands

php artisan make:swagger
php artisan swagger:cache
php artisan swagger:cache --clear
php artisan swagger:mock-server

OpenAPI export & caching

After make:swagger or swagger:cache, the file is written to:

• Path: public_path(config('swagger.cached_spec_path', 'doc.json'))
• Encoding: JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE

Regenerate after changing routes, controllers, FormRequests, or resources when you rely on a cached file for the JSON endpoint.

JSON endpoint resolution

The /{swagger.url}/json response is resolved by DocumentationController::resolveSwaggerSpecification():

Environment keys: SWAGGER_CACHED_SPEC_PATH, SWAGGER_USE_CACHED_SPEC (set to false to force live generation without deleting the file).

Mock server (experimental)

G4T provides an optional command that connects your auto-generated API documentation to a hosted mock experience so you can explore or demo your API surface more easily.

php artisan swagger:mock-server

Configure mock_server_url (default https://mock.g4t.io), and optionally MOCK_SERVER_APP_ID in .env to target a specific app without prompts.

Configuration reference

All keys live in config/swagger.php after publishing. Common environment variables are noted.

Resources

• This documentation (canonical URL)
• Video walkthrough
• Feature requests: Canny board
• OpenAPI / Swagger docs
• Laravel documentation
• Package repository
• License: MIT
• Maintainer: Hussein Alaa