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

Laravel API Documentation

A zero-configuration OpenAPI 3.1.0 documentation generator for Laravel. Analyzes your routes, controllers, form requests, and responses using AST parsing, PHP reflection, and optional runtime capture - then outputs a complete, valid OpenAPI spec without you writing a single annotation.

Requirements

• PHP 8.2+
• Laravel 10, 11, or 12

Installation

Publish the configuration file (optional):

Generate your documentation:

That's it. The package discovers your routes, analyzes your code, and writes an OpenAPI 3.1.0 spec to storage/app/public/api-documentation.json.

Table of Contents

• How It Works
• Quick Start
• Commands
• Runtime Capture
• PHP Attributes
• Configuration
• Tags & Documentation
• Documentation Viewers
• Output Formats
• Plugin System
• Built-in Plugins
• Creating a Plugin
• Integrations
• CI/CD Integration
• Security
• Credits
• License

How It Works

The package uses a 5-layer pipeline to generate documentation:

What Gets Analyzed Automatically

Requests:

• FormRequest validation rules (types, formats, min/max, enums, patterns, required/optional)
• Inline $this->validate() and Validator::make() calls
• $request->get(), $request->query(), $request->integer() method calls in controller bodies
• File upload detection (file, image rules) with automatic multipart/form-data content type
• Nested parameter structures (user.profile.name)

Responses:

• Return type declarations (JsonResource, JsonResponse, ResourceCollection, Spatie Data)
• Controller method body analysis (traces response()->json([...]) return statements)
• PHPDoc @return types including union types (UserData|AdminData produces oneOf)
• Abort statements (abort(404), abort_if()) for error responses
• Paginated responses with data, meta, and links structure
• JsonResource::toArray() analysis (property types, $this->when(), $this->whenLoaded(), $this->merge())

Query Parameters:

• FormRequest rules on GET routes become query parameters
• PHPDoc @queryParam annotations
• Pagination detection (paginate(), simplePaginate(), cursorPaginate()) adds page/per_page params

Errors:

• FormRequest presence adds 422 validation error
• auth/sanctum middleware adds 401 unauthorized
• Gate/authorize calls add 403 forbidden
• Route model binding adds 404 not found
• throttle middleware adds 429 rate limited
• Custom exception handler analysis for app-specific error schemas

Security:

• auth:sanctum, auth:api, jwt.auth middleware detected as Bearer token auth
• OAuth scopes extracted from scope: and scopes: middleware
• Sanctum abilities extracted from ability: and abilities: middleware

Quick Start

Zero-Config (Static Analysis)

For a standard Laravel API, no configuration is needed:

The package reads your routes, controllers, form requests, and resources to produce a spec. This typically achieves ~70% schema accuracy, depending on how explicitly typed your code is.

With Runtime Capture (Recommended)

Enable runtime capture to use real API responses from your test suite, bringing accuracy to 95%+:

1. Add to phpunit.xml:

2. Register the middleware in your test setup (e.g., TestCase.php or a service provider used during testing):

3. Run your tests, then generate:

The middleware captures request/response data to .schemas/responses/ during test runs. The generator merges this with static analysis to produce accurate schemas with real examples. See Runtime Capture for details.

With Attributes (Precision)

For routes where auto-detection falls short (proxy controllers, dynamic responses), add PHP 8 attributes:

Commands

api:generate - Generate Documentation

Examples:

api:lint - Lint Spec Quality

Reports coverage (summaries, descriptions, examples, error responses, request/response bodies), issues (errors, warnings), and a quality score (0-100) with a letter grade.

api:diff - Detect Breaking Changes

Compares two OpenAPI specs and reports breaking vs non-breaking changes. Detects removed endpoints, removed response fields, type changes, new required parameters, and added auth requirements.

api:types - Generate TypeScript Definitions

Generates TypeScript interfaces from your OpenAPI component schemas, including request/response types for operations that have an operationId.

api:clear-cache - Clear Caches

Without flags, clears both AST and capture caches.

api:plugins - List Registered Plugins

Shows all registered plugins with their names, priorities, and capabilities (which interfaces they implement).

Runtime Capture

Runtime capture records real HTTP request/response data during your test runs. This data is then merged with static analysis during generation.

How It Works

1. The CaptureApiResponseMiddleware intercepts API responses in local/testing environments (never in production)
2. For each response, it infers an OpenAPI schema from the JSON structure and stores it to .schemas/responses/
3. Captures are idempotent - if the schema structure hasn't changed between test runs, the file is not rewritten (no noisy git diffs)
4. Sensitive data (passwords, tokens, API keys, credit card numbers) is automatically redacted
5. During api:generate, the captured schemas are merged with static analysis results

Configuration

In config/api-documentation.php:

Merge Priority

Control whether static analysis or captured data takes precedence:

• static_first (default): Attributes > Static Analysis > Runtime Capture
• captured_first: Attributes > Runtime Capture > Static Analysis

Version Control

Consider committing .schemas/responses/ to version control. Captures are idempotent, so unchanged schemas produce no git diffs. This gives you:

• Documentation that works without running the full test suite
• A record of your API's response shapes over time
• Faster CI builds (skip test run, generate from committed captures)

PHP Attributes

Attributes give you precise control when auto-detection needs help. They always take the highest priority.

#[Tag]

Groups operations in the generated documentation. Applied at class or method level. Optionally includes a description (supports Markdown) that appears in ReDoc/Scalar as introductory content for the tag section.

Precedence: Config tags descriptions override #[Tag] attribute descriptions. See Tags & Documentation.

#[Summary] and #[Description]

Set the operation summary (short) and description (detailed). Also inferred from PHPDoc if not provided.

#[DataResponse]

Define response schemas explicitly. Repeatable for multiple status codes.

#[Parameter]

Enhance request body or response properties. Applied at class level (resources) or method level (form requests). Repeatable.

Type aliases are automatically normalized to valid OpenAPI types:

#[PathParameter]

Document path parameters. Repeatable.

#[QueryParameter]

Document query parameters explicitly. Repeatable.

#[ResponseHeader]

Document response headers. Repeatable.

#[RequestBody] and #[ResponseBody]

Low-level control over request/response schemas when you need full override.

#[ExcludeFromDocs]

Exclude a controller or specific method from documentation.

#[AdditionalDocumentation]

Link to external documentation.

#[DocumentationFile]

Route an endpoint to a specific documentation file (for multi-file setups).

#[IgnoreDataParameter]

Exclude a Spatie Data property from the request body schema.

PHPDoc Annotations

The package also reads PHPDoc blocks:

• The first line becomes the summary, the rest becomes the description
• @queryParam entries are extracted as query parameters
• @return type is used for response schema detection
• @deprecated marks the operation as deprecated

Configuration

After publishing the config (php artisan vendor:publish --tag="api-documentation-config"), the file is at config/api-documentation.php. Key sections:

OpenAPI Metadata

Route Filtering

Servers

Analysis

Code Samples

When enabled, adds x-codeSamples to each operation with working cURL, fetch, Guzzle, and requests examples.

Error Responses

Validation Rule Mappings

Tags & Documentation

Enrich your documentation viewers (ReDoc, Scalar) with tag descriptions, navigation groups, documentation-only pages, and external links. All settings are zero-config by default — empty arrays and null values produce no output.

Tag Descriptions

Add Markdown descriptions to tags. These appear as introductory content in tag sections.

Descriptions can also be set via the #[Tag] attribute:

Config descriptions take precedence over attribute descriptions.

Tag Groups (x-tagGroups)

Group tags into sections for the ReDoc/Scalar navigation sidebar:

This emits the x-tagGroups vendor extension recognized by ReDoc and Scalar. By default, any tags not assigned to a group are automatically collected into an "Other" group so they remain visible in the sidebar. To instead hide ungrouped tags (the default ReDoc/Scalar behavior), set:

Trait Tags (x-traitTag)

Add documentation-only tags that appear in the sidebar but aren't associated with any operations. Useful for guides, introductions, or changelogs:

Trait tags are emitted with x-traitTag: true and support full Markdown in the description.

External Documentation

Add a spec-level link to external documentation:

Set to null (default) to omit from the spec.

Domain Overrides

All four settings (tags, tag_groups, trait_tags, external_docs) can be overridden per domain:

Multi-Domain Support

Generate separate specs for different API domains:

Multi-File Support

Output multiple documentation files from a single app:

Use #[DocumentationFile('internal')] on controllers to route them to a specific file.

Documentation Viewers

Three built-in documentation UIs are available. Enable them in your config:

When any UI is enabled, a default hub page is registered at /documentation that redirects to your chosen default viewer.

To publish and customize the view templates:

Output Formats

JSON (default)

YAML

Requires the ext-yaml PHP extension, or falls back to a built-in converter.

Postman Collection

Exports a Postman Collection v2.1 file, grouped by tags, with auth headers, path/query parameters, and request body examples.

TypeScript Definitions

Plugin System

The package is built around 6 plugin interfaces. Each interface represents a specific analysis capability. All built-in analyzers use the same interfaces, so plugins have the same power as core functionality.

Plugin Interfaces

Every plugin must implement the base Plugin interface:

Priority System

Analyzers run in priority order (highest first). The first non-null result wins for request bodies; all results are collected for responses and query parameters.

Registering Plugins

Via config:

Via Composer auto-discovery (for package authors):

Programmatically at runtime:

Built-in Plugins

BearerAuthPlugin

Always active. Detects Bearer token authentication from auth:sanctum, auth:api, and jwt.auth middleware. Extracts OAuth scopes and Sanctum abilities.

PaginationPlugin

Always active. Detects paginate(), simplePaginate(), and cursorPaginate() calls via AST analysis. Wraps response schemas with data/meta/links pagination envelope.

CodeSamplePlugin

Enabled when code_samples.enabled is true in config. Generates working code examples in bash (cURL), JavaScript (fetch), PHP (Guzzle), and Python (requests) with proper auth headers and request bodies.

SpatieDataPlugin

Auto-detected when spatie/laravel-data is installed. Extracts request body schemas from Spatie Data DTO constructor properties. Handles optional properties, Lazy types, and nested DTOs with $ref deduplication.

SpatieQueryBuilderPlugin

Auto-detected when spatie/laravel-query-builder is installed. Extracts filter[...], sort, include, and fields query parameters from allowedFilters(), allowedSorts(), allowedIncludes(), and allowedFields() calls.

JsonApiPlugin

Auto-detected when timacdonald/json-api is installed. Generates proper JSON:API response schemas (data/attributes/relationships/links), sets content type to application/vnd.api+json, and adds the Accept header.

LaravelActionsPlugin

Auto-detected when lorisleiva/laravel-actions is installed. Extracts request schemas from Action classes using the AsController trait by analyzing rules() methods and handle() parameters.

Creating a Plugin

Here is a complete example of a plugin that adds a custom header to every operation:

Register it:

Plugin with Multiple Capabilities

A plugin can implement multiple interfaces:

The AnalysisContext Object

Every analyzer receives an AnalysisContext that provides:

• $ctx->routeInfo - Route metadata (URI, methods, middleware, parameters)
• $ctx->reflectionMethod - PHP ReflectionMethod of the controller action
• $ctx->reflectionClass - PHP ReflectionClass of the controller
• $ctx->ast - Parsed AST statements of the controller method body
• $ctx->classAttributes - PHP 8 attributes on the controller class
• $ctx->methodAttributes - PHP 8 attributes on the method

Plugin Safety

Plugins that throw during boot() are automatically unregistered and logged. A failing plugin never breaks documentation generation for other routes.

Community Plugin Ideas

Below are detailed implementation examples for plugins the community could build. Each example is a complete, working plugin that can be copied into your project and customized.

API Key Authentication

Detects custom middleware that validates API keys via headers or query parameters.

RFC 7807 Problem Details

Maps exceptions to standardized Problem Details responses. This is the only interface (ExceptionSchemaProvider) with no built-in implementation — a great opportunity for a community package.

League Fractal Transformers

Detects Fractal transformers and extracts response schemas by analyzing the transform() method's return array via AST parsing.

Versioning Headers

Detects API versioning strategies and documents the version parameter on each operation.

Register with custom configuration:

Cache Control Headers

Detects caching middleware and documents conditional request headers (ETag, If-None-Match).

Integrations

Spatie Laravel Data

When spatie/laravel-data is installed, Data objects used as controller method parameters are automatically documented:

Spatie Laravel Query Builder

When spatie/laravel-query-builder is installed, allowed filters, sorts, and includes are extracted as query parameters:

Laravel Actions

When lorisleiva/laravel-actions is installed, Action classes with the AsController trait are analyzed:

JSON:API (timacdonald/json-api)

When timacdonald/json-api is installed, JSON:API resources produce proper data/attributes/relationships response schemas.

CI/CD Integration

Generate on Deploy

Block Breaking Changes

Validate Spec Quality

Generate with Captures in CI

Security

The package is designed with security as a priority:

• Production safe: The capture middleware is gated behind environment checks and will never run in production, even if DOC_CAPTURE_MODE is accidentally set
• Sensitive data redaction: Passwords, tokens, API keys, credit card numbers, and SSNs are automatically redacted in captured examples
• No runtime overhead: The package only runs during documentation generation (api:generate) and optionally during testing (capture mode). It adds zero overhead to production request handling

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.