Download the PHP package abrha/laravel-data-docs without Composer

Laravel Data Docs

Generate beautiful API documentation automatically from Spatie's Laravel Data classes. This package integrates seamlessly with Knuckles Scribe to extract request and response schemas directly from your Data DTOs, eliminating manual documentation of API parameters.

Features

• Automatic Parameter Extraction: Automatically generates API documentation from Laravel Data classes
• Smart Attributes: Control documentation with #[Hidden], #[Example], #[QueryParameter], and #[ResponseData] attributes
• Laravel Data Validation Support: Automatic OpenAPI documentation for 30+ built-in Laravel Data validation attributes (#[Email], #[Min], #[Max], #[Uuid], etc.)
• Nested Objects Support: Handles nested Data objects and arrays with automatic dot notation and array notation
• Type-Safe: Leverages PHP 8.1+ attributes and Laravel Data's type system
• Extensible Architecture: Pipeline-based processing with custom stages, attribute processors, and type processors
• Scribe Integration: Works seamlessly with Knuckles Scribe for OpenAPI/Swagger documentation
• Zero Configuration: Works out of the box with sensible defaults

Installation

You can install the package via composer:

Scribe Configuration

Register the package strategies in your config/scribe.php:

Optionally, publish the config file:

Basic Usage

1. Create Your Data Classes

2. Use in Your Controllers

3. Generate Documentation

That's it! Scribe will automatically extract request parameters from CreateUserRequest and response structure from UserResponse.

Available Attributes

The package automatically processes Laravel Data validation attributes to generate comprehensive OpenAPI documentation with validation rules, formats, and descriptions.

#[Hidden]

Excludes a property from generated documentation. Useful for internal flags, metadata, or sensitive fields.

#[Example]

Provides custom example values for API documentation instead of auto-generated examples.

#[QueryParameter]

Marks a property as a URL query parameter (for non-GET requests). GET requests treat all parameters as query parameters by default.

#[ResponseData]

Specifies the response DTO class for a controller method. Applied to controller methods, not Data classes.

Laravel Data Validation Attributes

The package has built-in support for Laravel Data validation attributes. These automatically add OpenAPI validation rules, formats, and descriptions:

Format Attributes:

• #[Email] - Adds format: email
• #[Url], #[ActiveUrl] - Adds format: uri
• #[Uuid] - Adds format: uuid
• #[Password] - Adds format: password
• #[IPv4], #[IPv6], #[IP] - Adds IP format validation
• #[Date] - Adds format: date
• #[DateFormat] - Adds custom date format pattern
• #[Json] - Adds format: json

String Pattern Attributes:

• #[Alpha] - Only letters
• #[AlphaNumeric] - Letters and numbers
• #[AlphaDash] - Letters, numbers, dashes, underscores
• #[Lowercase] - Lowercase letters only
• #[Uppercase] - Uppercase letters only
• #[Ulid] - ULID pattern validation
• #[Regex] - Custom regex pattern
• #[StartsWith], #[EndsWith] - String prefix/suffix validation

Numeric Validation:

• #[Min], #[Max] - Minimum/maximum values
• #[Between] - Value between min and max
• #[GreaterThan], #[GreaterThanOrEqualTo] - Comparison validation
• #[LessThan], #[LessThanOrEqualTo] - Comparison validation
• #[MultipleOf] - Must be multiple of value
• #[Digits] - Exact number of digits
• #[DigitsBetween] - Digits between min and max

Example:

This automatically generates OpenAPI documentation with:

• Email format validation
• Name length constraints (3-50 characters)
• Age numeric constraints (18-120)
• UUID format for organizationId

Advanced Features

Nested Data Objects

The package automatically handles nested Data objects with dot notation:

Generated parameters:

• name (string)
• address (object)
• address.street (string)
• address.city (string)
• address.zipCode (string)

Arrays of Data Objects

Arrays of Data objects are automatically handled with array notation:

Generated parameters:

• customerName (string)
• items (object[])
• items[].productId (integer)
• items[].quantity (integer)
• items[].price (number)

Extending Functionality

The package provides four extension methods, ordered from simplest to most advanced:

1. Config File (Simplest)

The easiest way to customize documentation is through the config file. Define custom type mappings without writing any code:

Available configuration fields:

• type: OpenAPI type (string, integer, number, boolean, array, object)
• descriptions: Array of description strings
• pattern: Regex pattern for validation
• format: OpenAPI format (uuid, email, date-time, etc.)
• minimum: Minimum value for numbers
• maximum: Maximum value for numbers
• exclusiveMinimum: Exclusive minimum value
• exclusiveMaximum: Exclusive maximum value
• minLength: Minimum string length
• maxLength: Maximum string length
• minItems: Minimum array items
• maxItems: Maximum array items
• multipleOf: Number must be multiple of this value

When to use: Simple type mappings where you just need to specify OpenAPI properties declaratively.

2. Custom Type Processors

For more dynamic control over type processing, implement a CustomTypeProcessor:

Register in your AppServiceProvider:

When to use: When you need programmatic control over type documentation or need to generate dynamic examples/descriptions based on the class itself.

3. Custom Attribute Processors

Process custom or existing validation attributes by implementing an AttributeProcessor. This allows you to create reusable attributes that modify documentation behavior.

Step 1: Create your custom attribute:

Step 2: Create the processor:

Step 3: Register in your AppServiceProvider:

Step 4: Use in your Data classes:

When to use: When you need reusable, attribute-based validation logic that can be applied to multiple properties across different Data classes. Great for domain-specific validations.

4. Custom Pipeline Stages (Most Advanced)

For complete control over the processing pipeline, implement custom stages. This gives you access to the full context and allows modification at any point in the pipeline.

Register your stage in the pipeline:

When to use: When you need to:

• Implement complex cross-cutting concerns
• Modify processing behavior based on multiple factors
• Add entirely new processing steps to the pipeline
• Have full control over the documentation generation flow

Note: This requires deeper understanding of the package internals and how the pipeline processes contexts.

Extension Method Summary

How It Works

Pipeline Architecture

The package uses a pipeline pattern to process each property in your Data classes:

1. Context Creation: A ParameterContext object is created for each property
2. Pipeline Processing: The context flows through multiple stages:
   • HiddenStage: Checks for #[Hidden] attribute
   • TypeStage: Determines base type from PHP type hints
   • CustomTypeStage: Applies custom type configurations
   • AttributeProcessingStage: Processes all attributes using registered AttributeProcessors (includes 30+ built-in Laravel Data validation attributes)
   • TypeDescriptionStage: Generates type descriptions
   • DefaultValueStage: Extracts default values
   • DefaultValueDescriptionStage: Generates default value descriptions
   • RequiredStage: Determines if field is required
   • ExampleGenerationStage: Generates example values using Faker
3. Parameter Generation: Context is converted to API parameter format
4. OpenAPI Enhancement: The ExtendedOpenApiGenerator merges additional OpenAPI schema information into the final specification

Scribe Integration

The package provides three Scribe strategies and an OpenAPI generator:

• BodyParameters Strategy: Extracts request body parameters from Data classes
• QueryParameters Strategy: Extracts query parameters (GET requests or properties marked with #[QueryParameter])
• ResponseData Strategy: Extracts response structure from Data classes marked with #[ResponseData]
• ExtendedOpenApiGenerator: Merges custom OpenAPI schema information (default values, formats, patterns, etc.) extracted from Laravel Data attributes into the generated OpenAPI specification

These strategies automatically detect Data classes in your controller methods and generate comprehensive documentation with validation rules.

Development

This project uses a Docker-based development environment with a long-running container for fast command execution.

Getting Started

Start the development container (do this once):

The container stays running in the background. All subsequent commands execute instantly without container startup overhead.

Available Commands

Run ./dev help to see all available commands.

Testing

Run all tests:

Run tests with coverage:

Or using composer:

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

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

Credits

• Hamed Ehtesham
• All Contributors

License

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