README

Zero-annotation OpenAPI documentation generator for Laravel
Generate complete API docs from your existing code in seconds. No annotations required.

Documentation • Quick Start • Compare

The Problem

// ❌ Traditional approach: Annotations everywhere
/**
 * @OA\Post(
 *     path="/api/users",
 *     @OA\RequestBody(
 *         @OA\JsonContent(
 *             @OA\Property(property="name", type="string"),
 *             @OA\Property(property="email", type="string", format="email"),
 *             // ... 50 more lines of annotations
 *         )
 *     ),
 *     @OA\Response(response="200", description="Success")
 * )
 */
public function store(StoreUserRequest $request) { ... }

With Laravel Spectrum: Zero annotations needed. Your existing FormRequest and Resource classes are your documentation.

Quick Start (30 seconds)

# Install
composer require wadakatu/laravel-spectrum --dev

# Generate OpenAPI documentation
php artisan spectrum:generate

# View in browser (HTML, default: Swagger UI)
php artisan spectrum:generate --format=html
# Or choose a viewer
php artisan spectrum:generate --format=html --viewer=elements
# Open: storage/app/spectrum/openapi.html

That's it. Full OpenAPI 3.1 documentation generated from your existing code.

What Gets Analyzed Automatically

Your Code	Generated Documentation
`FormRequest::rules()`	Request body schemas with validation
`$request->validate([...])`	Inline validation rules
`API Resources`	Response schemas
Auth middleware (`auth:sanctum`)	Security schemes
Route parameters (`{user}`)	Path parameters with types
`@deprecated` PHPDoc	Deprecated operation flags

Key Features

Real-time Documentation

php artisan spectrum:watch
# Browser auto-refreshes when you change code

Built-in Mock Server

php artisan spectrum:mock
# Frontend team can develop without waiting for backend

Export to API Clients

php artisan spectrum:export:postman    # Postman collection
php artisan spectrum:export:insomnia   # Insomnia workspace
php artisan spectrum:sdk typescript    # Type-safe SDK client

Validate OpenAPI Spec

php artisan spectrum:validate storage/app/spectrum/openapi.json
php artisan spectrum:validate --generate --strict

Detect API Breaking Changes

php artisan spectrum:diff docs/openapi-v1.json docs/openapi-v2.json
php artisan spectrum:diff --against=last --format=json
php artisan spectrum:version-compare docs/openapi-v1.json docs/openapi-v2.json --migration-guide

High Performance

Parallel processing for large codebases
Incremental generation (only changed files)
Smart caching

Why Laravel Spectrum?

	Laravel Spectrum	Swagger-PHP	Scribe
Zero annotations	✅	❌	Partial
Setup time	30 sec	Hours	~30 min
FormRequest detection	✅	❌	✅
Mock server	✅	❌	❌
Live reload	✅	❌	❌
Postman/Insomnia export	✅	❌	✅
OpenAPI 3.1	✅	✅	❌

Requirements

PHP 8.2+
Laravel 11.x or 12.x

Compliance Check (Demo App Matrix)

Use the bundled demo apps to verify OpenAPI 3.0/3.1 compliance in one run:

./demo-app/check-openapi-compliance.sh

Details: demo-app/README.md

Documentation

📖 Full Documentation

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details. For mutation testing, run composer infection (full run with CI-aligned MSI thresholds).

License

Laravel Spectrum is open-source software licensed under the MIT license.

Made with ❤️ by wadakatu

wadakatu / laravel-spectrum

Maintainers

Details