diff --git a/README.md b/README.md index 75dc656..294e9d9 100644 --- a/README.md +++ b/README.md @@ -22,14 +22,13 @@ In modern event-driven architectures, documenting broadcast events is as crucial as documenting REST APIs. `laravel-async-api` bridges this gap for Laravel applications by automating the generation of AsyncAPI specifications. -It empowers you to document your broadcast events directly in your PHP code -using modern PHP 8 attributes, and generates fully compliant AsyncAPI 3.0 +It empowers you to document your broadcast events and generates fully compliant AsyncAPI 3.0 specifications with zero manual effort. ## Features -- **Zero-Effort Documentation:** Stop maintaining manual AsyncAPI files. Document your events directly in your PHP code. -- **Schema Integration:** Automatically extracts payload schemas from DTOs or models, ensuring your documentation always matches your code. +- **Zero-Effort Documentation:** Stop maintaining manual AsyncAPI files. Your events are documented automatically. +- **Schema Integration:** The broadcasting implementation structure, including data types, is inferred automatically to ensure your documentation always matches your code. - **Seamless Integration:** Works perfectly with Laravel's broadcasting system (Reverb, Pusher, Soketi). - **AsyncAPI 3.0 Compliant:** Generates specifications that follow the latest AsyncAPI standard. - **AI Agent Ready:** Includes an official [Laravel Boost](https://github.com/laravel/boost) skill to automatically teach AI agents (like Claude Code and Cursor) how to use this package in your project. @@ -45,52 +44,32 @@ class ChatMessage implements ShouldBroadcast } ``` -By simply implementing `ShouldBroadcast`, your event is instantly documented. The package uses static code analysis to automatically infer the payload schema directly from your properties, DTOs, and method returns without requiring any manual reflection or hints! - -If you want to customize the generated schema (like overriding the channel name or adding descriptions), you can optionally use the `#[AsyncApi]` attribute. If you want to hide an event, use `#[AsyncApiIgnore]`. +By simply implementing `ShouldBroadcast`, your event is instantly documented. The package uses static code analysis to automatically infer the payload schema directly from your properties, arrays, generics, and PHPDocs without requiring any manual reflection or hints! --- -## Installation +## 🚀 Quick Start + +### Step 1: Installation -1. Install the package via Composer: +Install the package via Composer: ```bash composer require victormgomes/async-api ``` -1. Publish the configuration file: +### Step 2: Publish the Configuration (Optional) + +If you need to customize the default settings (like server host, port, or title), publish the config file: ```bash php artisan vendor:publish --tag="async-api-config" ``` ---- - -## Quick Start - -### Step 1: Create a Broadcast Event - -```php -class ChatMessage implements ShouldBroadcast -{ - public function __construct( - public string $room, - public string $message, - public string $sender, - ) {} - - public function broadcastOn(): array - { - return [new Channel('chat.'.$this->room)]; - } -} -``` - -### Step 2: Access the Documentation +### Step 3: Access the Documentation -Visit `/docs/broadcast` in your application to view the interactive AsyncAPI -documentation. The raw JSON specification is also available at `/docs/broadcast/json`. +Visit `http://localhost/docs/broadcast` in your application to view the interactive AsyncAPI +documentation. The raw JSON specification is also available at `http://localhost/docs/broadcast/json`. --- diff --git a/docs/UPGRADING.md b/docs/UPGRADING.md index c22411b..c35fd48 100644 --- a/docs/UPGRADING.md +++ b/docs/UPGRADING.md @@ -1,3 +1,38 @@ # Upgrading -Instructions for upgrading between major versions will be added here when applicable. +## Upgrading To 2.0.0 From 1.x + +Version 2.0.0 introduces automated static analysis and brings some breaking changes to the configuration and routes. + +### 1. Routes Renamed + +The documentation viewer routes have been renamed to better reflect Laravel's broadcasting terminology: + +- `/docs/ws` is now `/docs/broadcast` +- `/docs/ws/json` is now `/docs/broadcast/json` + +If you have any custom links or bookmarks to the documentation, make sure to update them. + +### 2. Configuration Structure Flattened + +The configuration file `config/async-api.php` has been simplified and flattened. + +If you previously published the configuration file, you must publish the new version and migrate your settings: + +```bash +php artisan vendor:publish --tag="async-api-config" --force +``` + +Key changes in the config structure: + +- The `server` array has been flattened into `server_url`, `server_description`, and `server_protocol`. +- The `info` array has been flattened into `info_title`, `info_version`, and `info_description`. +- Added a `debug` option. + +### 3. Automated Schema Discovery (Plug-and-Play) + +The `#[AsyncApi]` attribute is now completely optional! + +You no longer need to add `#[AsyncApi]` to your events. The package will automatically scan any class implementing `ShouldBroadcast` and infer its schema via static code analysis. + +You can safely remove the `#[AsyncApi]` attribute from your events unless you need to override specific information (like a custom channel name or description). diff --git a/docs/installation-and-quick-start.md b/docs/installation-and-quick-start.md index 83a4faf..28c3a29 100644 --- a/docs/installation-and-quick-start.md +++ b/docs/installation-and-quick-start.md @@ -5,53 +5,30 @@ - PHP 8.3+ - Laravel 12.x or 13.x -## Installation +## Quick Start + +### Step 1: Installation -1. Install the package via Composer: +Install the package via Composer: ```bash composer require victormgomes/async-api ``` -1. Publish the configuration file: +### Step 2: Publish the Configuration (Optional) + +If you need to customize the default settings, publish the configuration file: ```bash php artisan vendor:publish --tag="async-api-config" ``` ---- - -## Quick Start - -### Step 1: Create a Broadcast Event - -Any event in your Laravel application that implements `ShouldBroadcast` is automatically discovered by the package. The schema of your event is parsed using static code analysis without requiring any manual documentation! - -```php -use Illuminate\Contracts\Broadcasting\ShouldBroadcast; -use Illuminate\Broadcasting\Channel; - -class ChatMessage implements ShouldBroadcast -{ - public function __construct( - public string $room, - public string $message, - public string $sender, - ) {} - - public function broadcastOn(): array - { - return [new Channel('chat.'.$this->room)]; - } -} -``` - -### Step 2: Access the Documentation +### Step 3: Access the Documentation -Visit `/docs/broadcast` in your application to view the interactive AsyncAPI +Visit `http://localhost/docs/broadcast` in your application to view the interactive AsyncAPI documentation powered by the default [AsyncAPI Studio](https://www.asyncapi.com/) viewer. The raw JSON -specification is also available at `/docs/broadcast/json`. +specification is also available at `http://localhost/docs/broadcast/json`. --- diff --git a/docs/introduction.md b/docs/introduction.md index 68dc846..d74c279 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -4,15 +4,13 @@ In modern event-driven architectures, documenting broadcast events is as crucial as documenting REST APIs. `laravel-async-api` bridges this gap for Laravel applications by automating the generation of AsyncAPI specifications. -Stop maintaining manual AsyncAPI files. Document your events directly in your -PHP code with a simple attribute, and let the package generate a fully compliant -AsyncAPI 3.0 specification. +Stop maintaining manual AsyncAPI files. Your events are documented automatically, +and the package generates a fully compliant AsyncAPI 3.0 specification. ## Features -- **Zero-Effort Documentation:** Stop maintaining manual AsyncAPI files. Document your events directly in your PHP code. -- **Attribute-Based:** Uses modern PHP 8 attributes for a clean and declarative developer experience. -- **Schema Integration:** Automatically extracts payload schemas from DTOs or models, ensuring your documentation always matches your code. +- **Zero-Effort Documentation:** Stop maintaining manual AsyncAPI files. Your events are documented automatically. +- **Schema Integration:** The broadcasting implementation structure, including data types, is inferred automatically to ensure your documentation always matches your code. - **Seamless Integration:** Works perfectly with Laravel's broadcasting system (Reverb, Pusher, Soketi). - **AsyncAPI 3.0 Compliant:** Generates specifications that follow the latest AsyncAPI standard. - **AI Agent Ready:** Includes an official [Laravel Boost](https://github.com/laravel/boost) skill to automatically teach AI agents (like Claude Code and Cursor) how to use this package in your project. @@ -28,7 +26,7 @@ class ChatMessage implements ShouldBroadcast } ``` -By simply implementing `ShouldBroadcast`, your event is instantly documented. The package uses static code analysis to automatically infer the payload schema directly from your properties, DTOs, and method returns without requiring any manual reflection or hints! +By simply implementing `ShouldBroadcast`, your event is instantly documented. The package uses static code analysis to automatically infer the payload schema directly from your properties, arrays, generics, and PHPDocs without requiring any manual reflection or hints! If you want to customize the generated schema (like overriding the channel name or adding descriptions), you can optionally use the `#[AsyncApi]` attribute. If you want to hide an event, use `#[AsyncApiIgnore]`.