Download the PHP package jkbennemann/laravel-api-documentation without Composer

Laravel API Documentation

Overview

Laravel API Documentation is a powerful package that automatically generates OpenAPI 3.0 documentation from your Laravel application code. It eliminates the need to manually write and maintain API documentation by intelligently analyzing your routes, controllers, requests, and responses.

Key Features

• Zero-Config Operation: Works out of the box with standard Laravel conventions
• Automatic Route Analysis: Scans all routes and extracts path parameters, HTTP methods, and middleware
• Smart Request Analysis: Extracts validation rules from FormRequest classes to document request parameters
• Dynamic Response Detection: Analyzes controller return types and method bodies to document responses
• Spatie Data Integration: First-class support for Spatie Laravel Data DTOs
• Resource Collection Support: Handles JsonResource and ResourceCollection responses
• Attribute Enhancement: Optional PHP 8 attributes for additional documentation control

Installation

1. Install via Composer

2. Publish Configuration (Optional)

3. Link Storage Directory

The package stores documentation in your storage directory. Make it accessible with:

Configuration

Default Settings

Out of the box, the package:

• Ignores vendor routes and HEAD/OPTIONS methods
• Disables Swagger/ReDoc UIs by default (can be enabled in config)
• Stores documentation at storage/app/public/api-documentation.json

Documentation Storage

To include the generated documentation in version control, update your .gitignore:

Custom Storage Location

For a more accessible location, add a custom disk in config/filesystems.php:

Then update your config:

CI/CD Integration

Add documentation generation to your deployment workflow:

Or add to your composer.json scripts:

Usage

Generating Documentation

This command scans your application routes and generates an OpenAPI 3.0 specification file at your configured location.

Viewing Documentation

By default, the documentation is accessible at:

• /documentation - Default UI (Swagger if enabled)
• /documentation/swagger - Swagger UI (if enabled)
• /documentation/redoc - ReDoc UI (if enabled)

To enable the UIs, update your configuration:

Specifying Files to Generate

Generate documentation for specific files only:

This generates api-v1.json based on your configuration settings.

How It Works

The package analyzes your Laravel application using several intelligent components:

1. Route Analysis: Scans all registered routes to identify controllers, HTTP methods, and path parameters
2. Controller Analysis: Examines controller methods to determine response types and structures
3. Request Analysis: Processes FormRequest classes to extract validation rules and convert them to OpenAPI parameters
4. Response Analysis: Detects return types and analyzes method bodies to determine response structures

Key Features

Zero-Configuration Detection

The package automatically detects and documents your API with minimal configuration:

Response Type Detection

• Analyzes controller return types (JsonResponse, ResourceCollection, etc.)
• Examines method bodies when return types aren't declared
• Supports union types (@return UserData|AdminData)
• Generates proper paginated response structures with data, meta, and links

Controller Support

• Works with traditional and invokable controllers
• Processes class-level and method-level attributes
• Handles mixed controller architectures seamlessly

Request Parameter Extraction

• Extracts validation rules from FormRequest classes
• Detects route parameters ({id}, {user}) automatically
• Supports nested parameter structures (user.profile.name)
• Handles parameters merged from route values in prepareForValidation

Validation & Type Detection

• Converts Laravel validation rules to OpenAPI types and formats
• Intelligently determines required vs. optional parameters
• Maps validation rules to appropriate formats (email → string with email format)

Resource & Collection Support

• Distinguishes between arrays and object responses
• Analyzes ResourceCollection for contained DTO types
• Supports DataCollectionOf attributes for nested collections

Recent Enhancements

Route Parameter Handling

• Route Value Detection: Properly handles parameters merged from route values in prepareForValidation
• Parameter Exclusion: Supports the IgnoreDataParameter attribute to exclude fields from body parameters

Spatie Data Integration

• Clean Schema Generation: Excludes internal Spatie Data fields (_additional and _data_context) from documentation
• DataCollectionOf Support: Properly documents nested collection structures with correct item types
• Union Type Support: Handles PHP 8+ union types in Spatie Data objects

Dynamic Response Analysis

• JsonResource Analysis: Improved detection of dynamic properties in JsonResource responses
• Method Body Parsing: Enhanced analysis of controller method bodies for response structure detection
• Paginated Response Support: Accurate documentation of paginated responses with proper structure

For more information on the OpenAPI specification, see OpenAPI Specification.

Enhancing Documentation with Attributes

While the package works automatically, you can enhance your documentation using PHP 8 attributes.

Controller Method Attributes

Available parameters:

• (required) status (int) - The status code of the response
• description (string) - A description of the response; default:''
• resource (null | string | array) - The resource class or Spatie Data object class that is returned by the route (e.g. UserResource::class, ['id' => 'string'], null); default:[]
• headers (null | array) - An array of response headers that are returned by the route (e.g. ['X-Token' => 'string']); default:[]

This will add a new field to the route object in the OpenAPI file:

Request/Resource attributes

For request or resource classes the same attributes can be used as for the routes, except for the Tag attribute.
In addition to that the following attributes are available:

1. PathParameter

This attribute can be used to specify additional information about path parameters in your routes.
It can be applied to controller methods to enhance the documentation of route parameters like {id}, {user}, etc.

Available parameters:

• (required) name (string) - The name of the path parameter (must match the route parameter)
• required (boolean) - Whether the parameter is required or not; default:true
• description (string) - A description of the parameter; default:''
• type (string) - The type of the parameter; default:'string'
• format (string) - The format of the parameter, considered as the sub-type as of OpenAPI; default:null
• example (mixed) - An example value for the parameter; default:null

2. Parameter

This attribute can be used to specify additional information about request or response parameters.
It can be applied at both class level and method level (e.g., on the rules() method of FormRequest classes).

Available parameters:

• (required) name (string) - The name of the parameter
• required (boolean) - Whether the parameter is required or not; default:false
• description (string) - A description of the parameter; default:''
• type (string) - The type of the parameter; default:'string'
• format (string) - The format of the parameter, considered as the sub-type as of OpenAPI; default:null
• example (mixed) - An example value for the parameter; default:null
• deprecated (boolean) - Whether the parameter is deprecated or not; default:false

Method Level Usage (FormRequest):

Class Level Usage (Resource):

📋 Query Parameter Annotations

In addition to attributes, the package supports @queryParam annotations for documenting query parameters:

This automatically generates query parameter documentation in the OpenAPI specification.

💡 Usage Examples & Best Practices

Here are some comprehensive examples showing how to leverage the automatic detection features:

Example 1: Complete Controller with Automatic Detection

Example 2: Advanced FormRequest with Nested Parameters

Example 3: Invokable Controllers with Class-Level Attributes

Laravel's invokable controllers (single-action controllers) are fully supported with class-level attribute processing:

Key Features for Invokable Controllers:

• Class-Level Attributes: #[Tag], #[Summary], #[Description] placed on the class are automatically detected
• Automatic Route Processing: Both Controller@method and Controller (invokable) route formats supported
• Response Type Detection: Same automatic detection as traditional controllers
• Request Validation: FormRequest classes processed normally
• Mixed Controller Support: Traditional and invokable controllers work seamlessly together

Route Registration:

Example 4: Resource with Spatie Data Integration

Example 5: Union Types with Multiple Response Formats

🎯 Best Practices

1. Leverage Automatic Detection: Let the package automatically detect response types and validation rules
2. Use Attributes for Enhancement: Add #[Parameter] and #[PathParameter] attributes only when you need to provide additional context
3. Document Complex Scenarios: Use @queryParam annotations for query parameters and union return types for multiple response formats
4. Structured Validation: Use nested validation rules for complex request structures
5. Consistent Naming: Use consistent parameter naming across your API for better documentation

Roadmap

✅ Completed Features

• [x] Advanced Response Type Detection: Automatic detection of return types, union types, and method body analysis
• [x] Smart Request Parameter Extraction: FormRequest validation rule processing and parameter attribute support
• [x] Invokable Controller Support: Full support for Laravel invokable controllers with class-level attribute processing
• [x] Path Parameter Documentation: #[PathParameter] attribute for route parameter enhancement
• [x] Query Parameter Support: @queryParam annotation processing
• [x] Nested Parameter Handling: Complex nested parameter structures with proper grouping
• [x] Spatie Data Integration: Full support for Spatie Data objects with automatic schema generation
• [x] Resource Collection Intelligence: Smart detection of collection types and pagination
• [x] Union Type Processing: DocBlock union type analysis with oneOf schema generation
• [x] Class Name Resolution: Automatic resolution of short class names to fully qualified names
• [x] Validation Rule Conversion: Laravel validation rules to OpenAPI type conversion

🚀 Planned Enhancements

• [ ] Enhanced Examples: More comprehensive example generation for request/response bodies
• [ ] Custom Validation Rules: Support for custom Laravel validation rules
• [ ] Advanced Response Headers: Automatic detection of response headers from controller methods
• [ ] File Upload Documentation: Automatic detection and documentation of file upload endpoints
• [ ] Middleware Documentation: Enhanced middleware detection and security scheme generation
• [ ] Custom Storage Options: Support for external storages (e.g., GitHub, S3 Bucket, etc.)
• [ ] Multi-version API Support: Support for API versioning in documentation
• [ ] Performance Optimization: Caching mechanisms for large applications
• [ ] Integration Testing: Built-in API testing capabilities based on generated documentation

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Jakob Bennemann
• All Contributors

License

The MIT License (MIT). Please see License File for more information.