rafoabbas/api-docs

Generate API documentation (Postman collections & OpenAPI specs) from PHP attributes and YAML files

v0.1.0 2026-01-29 08:18 UTC

Requires

• php: ^8.2
• illuminate/console: ^11.0|^12.0
• illuminate/routing: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0
• symfony/yaml: ^7.0

Requires (Dev)

• orchestra/testbench: ^9.0|^10.0
• pestphp/pest: ^3.0|^4.0
• pestphp/pest-plugin-laravel: ^3.0|^4.0

MIT

• Rauf Abbaszade

• documentation
• rest
• api
• attributes
• laravel
• swagger
• Postman
• openapi

README

Generate API documentation (Postman collections & OpenAPI specs) from PHP 8 attributes and YAML files.

Requirements

• PHP 8.2+
• Laravel 11+

Installation

composer require rafoabbas/api-docs

Quick Start

Add attributes to your controller:

use ApiDocs\Attributes\ApiFolder;
use ApiDocs\Attributes\ApiRequest;

#[ApiFolder('V1 / Auth')]
class AuthController extends Controller
{
    #[ApiRequest(name: 'Login', description: 'Authenticate user')]
    public function login(LoginRequest $request): JsonResponse
    {
        // ...
    }
}

Generate documentation:

php artisan api:generate

Output:

docs/
├── postman/
│   ├── {timestamp}-collection.json
│   └── {timestamp}-local.postman_environment.json
└── openapi/
    └── {timestamp}-openapi.yaml

Command Options

php artisan api:generate --format=postman      # Only Postman
php artisan api:generate --format=openapi      # Only OpenAPI
php artisan api:generate --format=both         # Both (default)
php artisan api:generate --name="My API"       # Custom name
php artisan api:generate --output=api-docs     # Custom output dir
php artisan api:generate --openapi-format=json # OpenAPI as JSON
php artisan api:generate --exclude=admin       # Exclude prefixes

Attributes

Attribute	Description
ApiRequest	Request name, description, order
ApiFolder	Group requests into folders
ApiBody	Request body (supports FormRequest merge)
ApiResource	Response Resource class
ApiVariable	Extract response values to variables
ApiHeader	Custom headers
ApiQueryParam	Query parameters
ApiAuth	Authentication config
ApiResponse	Example responses
ApiTest	Postman test scripts
ApiPreRequest	Pre-request scripts
ApiHidden	Exclude from docs

Auto-Resolve Features

• Request body from FormRequest rules()
• Response structure from Resource toArray()
• Authentication from middleware (auth:sanctum, auth)
• Route parameters from URI ({id} → :id)

Documentation

• Attributes - All attributes with examples
• Configuration - Config options
• YAML Definitions - YAML file format
• Auto-Resolve - Auto-detection features

Roadmap

• Swagger UI integration - Interactive docs at /api/docs
• Markdown export
• Validation rules to OpenAPI schema (required|email → type: string, format: email)
• #[ApiDeprecated] attribute
• Pagination auto-detect (LengthAwarePaginator response)
• PHP Enum to OpenAPI enum conversion
• Insomnia/Bruno export formats

License

MIT