API Doc Kit for Laravel

API Doc Kit is a developer-friendly package designed to simplify API documentation for Laravel projects. It automates the generation of robust OpenAPI documentation while allowing developers to retain flexibility and control. This package reduces the repetitive effort of manually defining API specs, making the process intuitive, maintainable, and efficient.

Key Features

| Feature | Description | Status | |--------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------| | Semi-Automated Documentation | Leverages PHP attributes to generate OpenAPI documentation with minimal configuration. | ✅ Available | | Model-Aware Operations | Automatically associates routes and parameters with Eloquent models for intelligent documentation generation. | ✅ Available | | Flexible Parameter Management | Detects route parameters, automatically assigns types, and generates descriptions with the ability to override globally. | ✅ Available | | Request & Response Handling | Automates OpenAPI property definitions for request classes and resource responses based on rules and model attributes. Detects file-upload rules and emits multipart/form-data bodies (format: binary); see Request Bodies. | ✅ Available | | Built-in Validation | Ensures all controllers, request classes, and responses adhere to defined documentation rules and highlights discrepancies.| ✅ Available | | SDK Generation | Generates TypeScript SDKs for front-end integration, including prebuilt methods for API calls (e.g., createUser()). | 🚀 Coming Soon | | Predefined Responses | Comes with customizable default responses like ValidationError, Unauthorized, and more. | ✅ Available | | Customizable Workflow | Supports custom route discovery, parameter overrides, and developer-defined extensions for unique project needs. | ✅ Available | | Global Configuration | Offers configuration for overriding parameter definitions, request behavior, and other package behavior. | ✅ Available | | CLI Warnings and Reports | Highlights issues like undefined parameters or missing descriptions directly in the CLI. | ✅ Available |

Installation

⚠️ This package is currently in active development and NOT production-ready.

Install via Composer:

composer require ismayil-dev/api-doc-kit:dev-main

Publish the config file:

php artisan vendor:publish --tag=api-doc-kit-config

Development Notice: This is an MVP release for testing and gathering feedback. APIs and features may change significantly. Use in production at your own risk.

Quick Start

1. Mark your controller methods

use IsmayilDev\ApiDocKit\Attributes\Resources\ApiEndpoint;
use IsmayilDev\ApiDocKit\Http\Responses\Contracts\CollectionResponse;
use IsmayilDev\ApiDocKit\Http\Responses\Contracts\SingleResourceResponse;

class UserController extends Controller
{
    #[ApiEndpoint(entity: User::class)]
    public function index(): CollectionResponse
    {
        return new ResourceResponse(User::all());
    }

    #[ApiEndpoint(entity: User::class)]
    public function show(User $user): SingleResourceResponse
    {
        return new ResourceResponse($user);
    }
}

2. Generate documentation

php artisan doc:generate

3. View generated OpenAPI docs

Your OpenAPI YAML will be at storage/app/documentation/openapi.yaml

Import this into Swagger UI, Postman, or any OpenAPI-compatible tool.

Why API Doc Kit?

• Time-Saving: Focus on building your application while Laravel Doc Kit handles the repetitive parts of API documentation.
• Flexible: Use predefined rules or customize behavior to match your project’s structure and conventions.
• Developer-Friendly: Clean syntax, powerful defaults, and detailed documentation ensure a smooth experience.

✅ What's Already Working

This MVP release includes:

• OpenAPI Documentation Generation - Generate complete OpenAPI YAML files via php artisan doc:generate
• Attribute-Based Documentation - Use #[ApiEndpoint], #[DataSchema], #[Enum] attributes
• DataSchema Support - Auto-generate schemas from DTOs and data classes
• Enum Support - Proper OpenAPI enum generation with SDK-friendly extensions
• Static String Entities - Use simple strings instead of requiring model classes
• Strict Mode Validation - CLI warnings for undocumented endpoints and missing attributes
• Route Coverage Validation - Ensure all API routes have proper documentation
• Smart Defaults - Automatic route parameter detection, type inference, and example generation
• Flexible Configuration - Global config for response schemas, error codes, and validation rules

🚀 Coming Soon

Features in active development:

• Laravel Resource Support - Generate schema from Laravel Resource classes and Advanced Eloquent Model Analyse and Support
• TypeScript SDK Generation - Auto-generate TypeScript SDKs with type-safe methods (working in test project, will be added to package)
• Advanced SDK Versioning - Semantic versioning for generated SDKs
• AI Integration - AI-powered documentation differentiation in human-readable and machine-readable formats
• Custom Processor Extensibility - Public API for custom Swagger processors
• Middleware Support - Support for middleware in API routes
• Api Versioning - Support for API versioning

📚 Documentation

Detailed guides for advanced features:

• DataSchema Usage - Auto-generate schemas from DTOs and data classes
• Request Bodies - Derive request body schemas from FormRequest rules, incl. nested objects & object arrays
• Enum Support - Proper OpenAPI enum handling for better SDK generation
• Static String Entities - Use strings instead of model classes
• Documentation Coverage - Validate all routes are documented
• operationId Generation - Control how operationId is derived from controllers
• Query Parameters - Typed query, header, and list-query parameter primitives

More documentation coming soon as features are added!

How It Works

API Doc Kit uses a combination of PHP attributes and smart defaults to document your API. Developers can define documentation attributes directly in controllers, request classes, and resources, while the package handles the heavy lifting.

Contributing

Contributions are welcome! If you have ideas, bug reports, or feature requests, feel free to open an issue or submit a pull request.

License

Laravel Doc Kit is open-source software licensed under the MIT license.