Download the PHP package ironcurtaindev/easy-doc without Composer

EasyDoc 📚

A lightweight, developer-friendly API documentation generator for Laravel.

Stop writing YAML manually. EasyDoc auto-generates beautiful Markdown documentation, OpenAPI (Swagger) specs, Postman collections, and even a fully typed TypeScript SDK directly from your Laravel codebase using a fluent, expressive API.

🚀 Features

• Fluent API: Define documentation directly in your Controller logic using document() function.
• PHP 8 Attributes: Alternatively, use #[DocAPI], #[DocParam], #[DocHeader], #[DocResponse] attributes for cleaner code.
• Automatic Schema Discovery: Eloquent models are automatically scanned.
• Mobile Ready: Generated OpenAPI 3.0 & Swagger 2.0 specs are perfect for generating iOS (Swift) and Android (Kotlin) clients via generic code generators.
• Multi-Format Output: Markdown, OpenAPI 3.0, Swagger 2.0, Postman, TypeScript SDK.
• Configurable Headers: Define global authentication headers once in your config.

🎯 Why Easy-Doc?

🏢 For Teams: The "Bus Factor" Solution

If your backend developer leaves, does the next person know how the API works? With Easy-Doc, documentation lives inside the code.

• Knowledge Transfer: The docs are right next to the logic.
• Self-Explaining Code: The Fluent API (->name('Login')) makes intent clear.

🛡️ Real-World Resilience

Projects get paused. Clients change requirements. Developers changes.

• Project Restarts: Paused for 6 months? Since docs are code, they don't "rot". You pick up exactly where you left off.
• Change Requests: When a client changes a requirement, you change the code AND the doc in the same file. No desync. No "I forgot to update the wiki".

🧠👨‍💻 For Solo Devs: Your "External Brain"

Working alone? Easy-Doc acts as your memory.

• Completeness Check: By explicitly defining endpoints, you instantly spot missing descriptions or edge cases.
• Future-Proofing: Come back to your project 6 months later and know exactly what every endpoint does without re-reading the execution logic.

It bridges the gap between "Code" and "Explanation".

📦 Installation

Install via Composer:

Stable Version (Recommended)

Development Version (Bleeding Edge)

📋 Requirements

• Laravel: 13.4+
• PHP: 8.3+

Need Laravel 11/12 support? Use a pre-1.0 release line.

Publish the configuration (Optional):

⚙️ Configuration (Auto-Discovery)

Model Auto-Discovery

By default, EasyDoc scans your app/Models directory. You just need to ensure your models are standard Eloquent models.

Reusable Authentication Headers

Define headers that appear frequently across your API. Then reference them by name in your endpoints.

Then reference them in your attributes:

Or with the document() function:

Default Headers

Headers included in ALL endpoints automatically:

Tip: Use addDefaultHeaders: false in #[DocAPI] to skip default headers for a specific endpoint.

📖 Usage Guide

Since schemas are auto-discovered, you focus purely on Documenting Endpoints.

Scenario: A User has one Partner and many Places.

1. Document Your Endpoints 📝

Use the document() helper in your Controllers.

Scenario: User Registration (Auth)

Scenario: User Partner (One-to-One)

Demonstrates using setSuccessObject to automatically document a model response.

Scenario: User Places (One-to-Many & Pagination)

Demonstrates setSuccessPaginatedObject for paginated responses.

Alternative: PHP 8 Attributes 🏷️

New in v0.3! You can now define documentation using PHP 8 Attributes instead of the document() function. This keeps your documentation metadata outside the function body for cleaner code.

Benefits of Attributes:

• Cleaner controller methods - Business logic is separated from documentation
• IDE support - Better autocomplete and validation
• Standard PHP pattern - Follows modern PHP 8+ conventions
• Compile-time validation - PHP validates attribute syntax
• Full feature parity - All document() options available as attributes

Example: Login with Attributes

Available Attributes

🆕 Auto-Documenting FormRequests with #[DocRequest]

Stop repeating yourself! If you use Laravel's FormRequest for validation, you can automatically generate documentation parameters from your rules.

EasyDoc parses the rules() method and converts them into #[DocParam] entries automatically, including types and required status.

DocAPI Options (Complete Reference)

DocParam Options

DocHeader Options

DocResponse Options

Complete Real-World Example

Here's a production-ready example using all available attribute features:

Note: Both approaches (document() function and Attributes) are fully supported. Use whichever fits your coding style!

2. View Your Documentation 👁️

Once you have defined your endpoints, view them in the browser.

Make sure to enable the viewer in your .env:

Then visit:

• Public Documentation (Redoc): http://your-app.test/api-docs (Beautiful, client-facing docs)
• Modern API Reference (Scalar): http://your-app.test/docs/scalar (Interactive, dark mode, beautiful)
• Dashboard (Swagger UI): http://your-app.test/easy-doc (Interactive testing dashboard)

🛠️ API Responses (Trait)

EasyDoc provides a convenient trait ApiResponses to standardize your API responses.

Step 1: Use the Trait in your Controller

Available Methods:

Standard Response Structure:

🧩 Advanced: Extra API Columns

Sometimes your API returns data that isn't a direct column in your database (e.g., computed attributes, relationships, or tokens). You can document these using the HasExtraApiColumns interface on your Model.

🚀 Generate Command

Run the artisan command to generate all formats:

This will generate:

• public/docs/openapi.json (OpenAPI 3.0)
• public/docs/swagger.json (Swagger 2.0)
• public/docs/postman_collection.json (Postman)
• public/docs/types.ts (TypeScript Interfaces)

Performance & Caching ⚡

In production, parsing Attributes and Reflection on every request can be slow. EasyDoc provides caching commands to optimize performance.

Cache Documentation: Serializes the parsed documentation to bootstrap/cache/easy-doc.php, bypassing the reflection process in subsequent requests.

Clear Cache: Removes the cached file.

Recommendation: Add php artisan easy-doc:cache to your deployment script.

License

The MIT License (MIT).

📚 Deep Dive Reference

Parameter Types & Validation

The Param class offers a rich set of validation and typing options.

Available Types:

• Param::TYPE_STRING
• Param::TYPE_INT
• Param::TYPE_BOOLEAN
• Param::TYPE_ARRAY
• Param::TYPE_FILE (See File Uploads below)
• Param::TYPE_NUMBER / TYPE_FLOAT

File Uploads 📂

To document file uploads, use setConsumes and Param::TYPE_FILE.

TypeScript SDK Generation 🟦

EasyDoc can generate a fully typed TypeScript SDK for your frontend.

1. Enable it in config/easy-doc.php:

2. Auto-Discovery: Your Eloquent models in app/Models are automatically converted to TypeScript interfaces (e.g., interface User { ... }).

Advanced Configuration

Custom Response Wrapper

If your API wraps every response (e.g., inside data), configure it globally to keep your docs accurate.

Multiple Environments

Document your Staging and Production servers so users can switch between them in the UI.

Rate Limiting & Deprecation

🚀 Developer-Friendly Features (v0.4)

DocGroup - Controller-Level Defaults

Apply common settings to all endpoints in a controller. No more repeating group, version, tags on every method!

DocGroup Properties:

DocError - Error Response Presets

Reference common error responses from config instead of writing them out every time.

Step 1: Define presets in config:

Step 2: Use in controllers:

Available Default Presets:

• validation (422)
• unauthenticated (401)
• unauthorized (403)
• not_found (404)
• rate_limit (429)
• server_error (500)

Param Templates - Reusable Parameter Definitions

Define common parameters once, reuse everywhere.

Step 1: Define templates in config:

Step 2: Use in controllers:

Override template values:

Comparison: Before vs After

`