README

Write code. Laravel API Docx writes the docs.

AI-powered automatic API documentation generator for Laravel 12

Features • Installation • Usage • Examples • Configuration • Contributing

🚀 Features

🤖 AI-Powered Intelligence

Smart Documentation: Automatically generates meaningful descriptions using OpenAI GPT-4
Advanced Analysis: Creates request/response examples, parameter documentation, and error responses
Context-Aware: Understands Laravel patterns and generates relevant documentation
Intelligent Caching: Avoids redundant AI API calls with smart caching

📝 Multiple Output Formats

Markdown: Human-readable documentation perfect for GitHub/GitLab
OpenAPI 3.0: Industry-standard specification for Swagger UI integration
Postman Collection: Ready-to-import API testing collections
ReDoc HTML: Beautiful, interactive documentation pages

🔍 Smart Route Analysis

Automatic Discovery: Scans all API routes (starting with api/)
Controller Analysis: Extracts controller and method information
DocBlock Integration: Uses existing docblocks when available
Middleware Detection: Analyzes route middleware and requirements

⚡ Developer Experience

Zero Configuration: Works out of the box with sensible defaults
Watch Mode: Automatically regenerates documentation on file changes
Progress Indicators: Beautiful CLI output with emojis and progress bars
Error Handling: Comprehensive error reporting and recovery

🎯 Laravel 12 Ready

Modern PHP: Built for PHP 8.3+ with latest language features
Laravel 12: Fully compatible with the latest Laravel version
Performance: Optimized for speed and memory efficiency
Security: Follows Laravel security best practices

📦 Installation

Via Composer

composer require digitalcorehub/laravel-api-docx

The package will automatically register itself with Laravel.

Publish Configuration

php artisan vendor:publish --provider="DigitalCoreHub\LaravelApiDocx\LaravelApiDocxServiceProvider" --tag="api-docs-config"

Environment Setup

Add your OpenAI API key to your .env file:

OPENAI_API_KEY=your-openai-api-key-here
OPENAI_API_ENDPOINT=https://api.openai.com/v1/chat/completions

🎯 Usage

Quick Start

Generate documentation for all your API routes:

php artisan api:docs

This creates:

📝 docs/api.md - Markdown documentation
🔗 docs/api.json - OpenAPI 3.0 specification
📮 docs/api.postman.json - Postman collection
🌐 docs/api.html - Interactive ReDoc page

Advanced Usage

Format Selection

# Generate specific formats
php artisan api:docs --format=markdown
php artisan api:docs --format=openapi
php artisan api:docs --format=postman
php artisan api:docs --format=redoc

# Generate all formats (default)
php artisan api:docs --format=all

AI-Enhanced Documentation

# Generate with advanced AI features
php artisan api:docs --advanced

# Features include:
# - Request/response examples
# - Parameter documentation
# - Error response mapping
# - Smart tagging and grouping

Watch Mode

# Automatically regenerate on file changes
php artisan api:docs --watch

# Combine with advanced AI
php artisan api:docs --advanced --watch

Custom Output Paths

# Custom output directory
php artisan api:docs --output=/custom/docs/

# Custom file for specific format
php artisan api:docs --format=markdown --output=/path/to/api.md

🔧 How It Works

graph TD
    A[API Routes] --> B[Route Collector]
    B --> C[Controller Analysis]
    C --> D{DocBlock Exists?}
    D -->|Yes| E[Extract DocBlock]
    D -->|No| F[AI Generation]
    E --> G[Documentation Builder]
    F --> H[OpenAI API]
    H --> I[Cache Result]
    I --> G
    G --> J[Format Generators]
    J --> K[Markdown]
    J --> L[OpenAPI]
    J --> M[Postman]
    J --> N[ReDoc HTML]

Process Flow

🔍 Route Discovery: Scans all registered routes and filters API routes
📊 Controller Analysis: Extracts controller, method, and middleware information
📚 DocBlock Processing: Checks for existing documentation in controller methods
🤖 AI Enhancement: Generates descriptions, examples, and parameters using OpenAI
💾 Smart Caching: Stores AI results to avoid redundant API calls
📝 Documentation Generation: Creates comprehensive docs in multiple formats

📋 Examples

Markdown Output

# API Documentation

Generated automatically by **digitalcorehub/laravel-api-docx**.

## GET|POST /api/users

- **Controller:** `App\Http\Controllers\UserController@index`
- **Name:** `users.index`
- **Middleware:** `auth,throttle:60,1`

Retrieves a paginated list of users with optional filtering and sorting capabilities.

### Parameters
- `page` (query): Page number for pagination
- `per_page` (query): Number of items per page (max 100)
- `search` (query): Search term for filtering users

### Example Request
```json
GET /api/users?page=1&per_page=20&search=john

Example Response

{
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 100
  }
}

GET /api/users/{user}

Controller: App\Http\Controllers\UserController@show
Name: users.show
Middleware: auth

Displays detailed information about a specific user including profile data and settings.

Parameters

user (path): User ID or username

Example Response

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "profile": {
    "avatar": "https://example.com/avatar.jpg",
    "bio": "Software Developer"
  },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}


### OpenAPI 3.0 Output

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "API Documentation",
    "description": "Generated automatically by digitalcorehub/laravel-api-docx",
    "version": "1.0.0",
    "contact": {
      "name": "API Support",
      "email": "support@example.com"
    }
  },
  "servers": [
    {
      "url": "https://api.example.com",
      "description": "Production Server"
    },
    {
      "url": "http://localhost:8000",
      "description": "Development Server"
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "summary": "List users",
        "description": "Retrieves a paginated list of users with optional filtering and sorting capabilities.",
        "tags": ["Users"],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "Page number for pagination",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "description": "Number of items per page",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/User"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PaginationMeta"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "name": {
            "type": "string",
            "example": "John Doe"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "john@example.com"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}

Postman Collection

{
  "info": {
    "name": "API Documentation",
    "description": "Generated automatically by digitalcorehub/laravel-api-docx",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "version": "1.0.0"
  },
  "item": [
    {
      "name": "Users",
      "description": "User management endpoints",
      "item": [
        {
          "name": "List Users",
          "request": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json",
                "type": "text"
              }
            ],
            "url": {
              "raw": "{{base_url}}/api/users?page=1&per_page=20",
              "host": ["{{base_url}}"],
              "path": ["api", "users"],
              "query": [
                {
                  "key": "page",
                  "value": "1",
                  "description": "Page number"
                },
                {
                  "key": "per_page",
                  "value": "20",
                  "description": "Items per page"
                }
              ]
            },
            "description": "Retrieves a paginated list of users with optional filtering and sorting capabilities."
          }
        }
      ]
    }
  ],
  "variable": [
    {
      "key": "base_url",
      "value": "http://localhost:8000",
      "type": "string"
    }
  ]
}

⚙️ Configuration

AI Settings

// config/api-docs.php
'ai' => [
    'provider' => 'openai',
    'model' => 'gpt-4o-mini', // or 'gpt-4', 'gpt-3.5-turbo'
    'api_key' => env('OPENAI_API_KEY'),
    'endpoint' => env('OPENAI_API_ENDPOINT', 'https://api.openai.com/v1/chat/completions'),
    'timeout' => 15,
    'max_tokens' => 500,
],

Output Paths

'output' => base_path('docs/api.md'),
'openapi_output' => base_path('docs/api.json'),
'postman_output' => base_path('docs/api.postman.json'),
'redoc_output' => base_path('docs/api.html'),

Caching

'cache' => [
    'enabled' => true,
    'store_path' => storage_path('app/laravel-api-docx-cache.php'),
    'ttl' => 3600, // 1 hour
],

Advanced Options

'advanced' => [
    'generate_examples' => true,
    'include_middleware' => true,
    'include_validation_rules' => true,
    'group_by_controller' => true,
    'sort_routes' => 'uri', // 'uri', 'method', 'name'
],

🧪 Testing

Run Tests

# Run all tests
composer test

# Run with coverage
composer test-coverage

# Run specific test suite
./vendor/bin/phpunit --testsuite=Unit
./vendor/bin/phpunit --testsuite=Feature

Code Quality

# Check code style
composer check-style

# Fix code style issues
composer fix-style

# Run static analysis
composer analyse

# Security audit
composer audit

🚀 Performance

Optimization Tips

Enable Caching: Always enable caching in production
Use Watch Mode: For development, use --watch to avoid manual regeneration
Selective Generation: Use --format to generate only needed formats
AI Optimization: Use gpt-4o-mini for faster AI responses

Benchmarks

Operation	Time	Memory
Route Collection	~50ms	~2MB
DocBlock Parsing	~100ms	~1MB
AI Generation (10 routes)	~2s	~5MB
Markdown Generation	~20ms	~1MB
OpenAPI Generation	~30ms	~2MB

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/digitalcorehub/laravel-api-docx.git
cd laravel-api-docx

# Install dependencies
composer install

# Run tests
composer test

# Check code style
composer check-style

Pull Request Process

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📊 Roadmap

Upcoming Features

GraphQL Support: Generate documentation for GraphQL APIs
Custom Themes: Multiple ReDoc themes and customization options
API Versioning: Support for multiple API versions
Export Options: PDF, Word, and other format exports
Team Collaboration: Multi-user documentation editing
API Testing: Built-in API testing capabilities
Webhook Integration: Automatic documentation updates via webhooks

Version History

v1.0.0 - Initial release with basic features
v1.1.0 - Added Postman and ReDoc support
v1.2.0 - Advanced AI features and watch mode
v1.3.0 - Performance optimizations and caching improvements

🛡️ Security

Security Policy

We take security seriously. If you discover a security vulnerability, please:

DO NOT create a public GitHub issue
Email us at security@digitalcorehub.com
Include detailed information about the vulnerability
We'll respond within 24 hours

Security Features

Input Validation: All inputs are validated and sanitized
API Key Protection: OpenAI API keys are never logged or exposed
File Permissions: Generated files have appropriate permissions
Dependency Scanning: Regular security audits of dependencies

📞 Support

Getting Help

📖 Documentation: Check this README and Wiki
🐛 Bug Reports: GitHub Issues
💬 Discussions: GitHub Discussions
📧 Email: info@digitalcorehub.com

Community

🌟 Star us on GitHub if you find this project helpful
🐦 Follow us on Twitter @DigitalCoreHub
💼 LinkedIn: Digital Core Hub

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Laravel Team for the amazing framework
OpenAI for the powerful AI capabilities
ReDoc for the beautiful documentation UI
Postman for the API testing platform
All Contributors who help make this project better

Made with ❤️ by Digital Core Hub

Website • GitHub • Twitter • LinkedIn

If this project helps you, please give it a ⭐ on GitHub!

digitalcorehub / laravel-api-docx

Maintainers

Details

README

🚀 Features

🤖 AI-Powered Intelligence

📝 Multiple Output Formats

🔍 Smart Route Analysis

⚡ Developer Experience

🎯 Laravel 12 Ready

📦 Installation

Via Composer

Publish Configuration

Environment Setup

🎯 Usage

Quick Start

Advanced Usage

Format Selection

AI-Enhanced Documentation

Watch Mode

Custom Output Paths

🔧 How It Works

Process Flow

📋 Examples

Markdown Output

Example Response

GET /api/users/{user}

Parameters

Example Response

Postman Collection

⚙️ Configuration

AI Settings

Output Paths

Caching

Advanced Options

🧪 Testing

Run Tests

Code Quality

🚀 Performance

Optimization Tips

Benchmarks

🤝 Contributing

Development Setup

Pull Request Process

📊 Roadmap

Upcoming Features

Version History

🛡️ Security

Security Policy

Security Features

📞 Support

Getting Help

Community

📄 License

🙏 Acknowledgments