Laravel Swagger Laravel Package

Getting Started

Install the package with Composer and let Laravel discover it (or register the provider manually on older Laravel versions):

composer require kevupton/laravel-swagger

If you are not using package auto-discovery, add the service provider to config/app.php:

Kevupton\LaravelSwagger\LaravelSwaggerServiceProvider::class,

Publish the package config so you can control where the generated spec is written and which routes are scanned:

php artisan vendor:publish --provider="Kevupton\LaravelSwagger\LaravelSwaggerServiceProvider"

Then generate the documentation:

php artisan swagger:generate

The first place to look is the published config/swagger.php (or the package README if your version names it differently). It controls the output path, the route/controller paths to scan, and any base API metadata. Your first use case should be small: pick one controller, add a single annotated endpoint, run the generate command, and open the resulting JSON in Swagger UI or a JSON viewer. Confirm the path, method, and parameters appear before annotating the rest of the API.

A minimal annotated endpoint looks roughly like this (this package targets the older @SWG annotation style; check which swagger-php version your install pulls in):

/**
 * @SWG\Get(
 *     path="/api/users/{id}",
 *     tags={"Users"},
 *     summary="Fetch a single user",
 *     @SWG\Parameter(name="id", in="path", required=true, type="integer"),
 *     @SWG\Response(response=200, description="User returned"),
 *     @SWG\Response(response=404, description="Not found")
 * )
 */
public function show($id)
{
    //
}

Implementation Patterns

Annotate controllers, not routes. The generator typically scans controller docblocks and maps them to registered Laravel routes. Keep annotations directly above the controller action so the method/path pairing stays obvious during code review. Avoid scattering annotations across service classes.

Centralize global metadata. Put @SWG\Info, security definitions, and shared schemas in one dedicated docblock file or a base ApiController. This prevents every controller from repeating title, version, and auth configuration, and gives you one place to update when the API version changes.

Define reusable schemas for models. Instead of duplicating response shapes, declare @SWG\Definition blocks for your Eloquent resources and reference them with @SWG\Schema(ref="#/definitions/User"). This keeps generated docs aligned with your API resources and reduces annotation drift.

Use tags to mirror your domain. Tag endpoints by resource (Users, Orders, Billing) so Swagger UI groups them sensibly. This is especially useful when the generated spec covers a large route surface.

Regenerate as part of your workflow. Add generation to a Composer script or CI step so docs do not go stale:

"scripts": {
    "docs": "php artisan swagger:generate"
}

For local development, run it after changing annotations; for CI, generate and diff or publish the artifact so missing annotations fail review.

Serve the spec deliberately. Point Swagger UI at the generated JSON file, or expose it through a route in non-production environments. Keep documentation routes disabled or protected in production unless the API is public.

Integrate with request validation. Where possible, reflect Laravel validation rules in the annotation parameters (types, required flags, enums). This keeps the generated contract close to what the application actually accepts and makes the docs useful to frontend and mobile consumers.

Gotchas and Tips

• Check framework compatibility first. This is a small, older package. Confirm the Laravel and PHP versions it supports against your application before adopting it; you may need to pin versions or fork it. If it does not fit, l5-swagger (swagger-php integration) or dedoc/scramble (annotation-free generation) are common alternatives.
• Malformed annotations fail quietly. A missing comma or wrong annotation namespace can cause an endpoint to be skipped without an obvious error. After generating, inspect the JSON for the endpoint you just added rather than assuming success.
• Clear caches before generating. Run php artisan config:clear and php artisan route:clear if routes or config changes are not reflected. Stale route caches are a frequent cause of missing or duplicated paths.
• Watch route prefixes and domains. Routes registered under API prefixes, subdomains, or custom route groups may not be scanned as expected. Verify the config's scan paths include the controllers you care about, and check the generated basePath/servers entry.
• Output permissions matter. The generator writes to a configured path (often under public/ or storage/). Ensure the web server and CLI user can write there, or generation will fail or silently produce an empty file.
• Docblock parsing is namespace-sensitive. If you use @SWG annotations, make sure the swagger-php annotation classes are resolvable and imported or fully qualified as required by your version. Mixing @SWG and @OA styles in the same codebase will produce confusing results.
• Keep annotations close to the code they describe. The main long-term failure mode is documentation drift. Treat annotation changes as part of the endpoint change, and review generated diffs in pull requests.
• Extension points are limited but usable. You can customize output location and scanned paths through config, and override or bind services via the package's service provider if you need custom generation behavior. Before extending, read the package source—at this size, the implementation is short enough to audit directly.
• Do not rely on it as your only contract test. Generated Swagger is documentation, not validation. Pair it with feature tests or contract tests so the spec and actual responses stay honest.