From ba34c005d9cec32c6aa4ec3f3212b52aecb9f0d6 Mon Sep 17 00:00:00 2001 From: "Victor M. Gomes" Date: Tue, 28 Jul 2026 19:28:08 -0300 Subject: [PATCH 1/4] chore: require laravel/surveyor directly and fix md formatting --- composer.json | 1 + docs/configuration.md | 28 ++++++++++++++-------------- docs/index.md | 4 ++-- docs/usage.md | 2 +- 4 files changed, 18 insertions(+), 17 deletions(-) diff --git a/composer.json b/composer.json index 8c77bb0..de7d97d 100644 --- a/composer.json +++ b/composer.json @@ -42,6 +42,7 @@ "illuminate/support": "^12.0 || ^13.0", "illuminate/view": "^12.0 || ^13.0", "laravel/ranger": "^0.2.5", + "laravel/surveyor": "^0.2.6", "spatie/laravel-data": "^4.0", "spatie/laravel-package-tools": "^1.16", "symfony/finder": "^7.0 || ^8.0" diff --git a/docs/configuration.md b/docs/configuration.md index 92d403d..388cbae 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -4,20 +4,20 @@ After publishing the configuration file (`php artisan vendor:publish --tag="asyn ## Options -| Option | Description | -| ---------------------------- | ------------------------------------------------------------ | -| `asyncapi_version` | The AsyncAPI specification version (default: `3.0.0`). | -| `default_content_type` | Default content type for all messages. | -| `info_title` | The title of your API. | -| `info_version` | The version of your API. | -| `info_description` | A short description of your API. | -| `server_host` | The broadcasting server host (e.g. `localhost`). | -| `server_port` | The broadcasting server port (e.g. `8080`). | -| `server_scheme` | The HTTP scheme used to connect (e.g. `https` or `http`). | -| `server_app_key` | The Reverb/Pusher app key. | -| `security_description` | The description of the Bearer authentication method. | -| `middleware` | Middleware to assign to the AsyncAPI routes. | -| `debug` | Enable detailed logging during scanning (default: `true`). | +| Option | Description | +| ---------------------- | ---------------------------------------------------------- | +| `asyncapi_version` | The AsyncAPI specification version (default: `3.0.0`). | +| `default_content_type` | Default content type for all messages. | +| `info_title` | The title of your API. | +| `info_version` | The version of your API. | +| `info_description` | A short description of your API. | +| `server_host` | The broadcasting server host (e.g. `localhost`). | +| `server_port` | The broadcasting server port (e.g. `8080`). | +| `server_scheme` | The HTTP scheme used to connect (e.g. `https` or `http`). | +| `server_app_key` | The Reverb/Pusher app key. | +| `security_description` | The description of the Bearer authentication method. | +| `middleware` | Middleware to assign to the AsyncAPI routes. | +| `debug` | Enable detailed logging during scanning (default: `true`). | ## Debug Mode diff --git a/docs/index.md b/docs/index.md index 56db5f2..a61d1e9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,12 +25,12 @@ features: # 🚀 Quick Start -### 1. Install the package +## 1. Install the package ```bash composer require victormgomes/async-api ``` -### 2. Access the documentation +## 2. Access the documentation Visit `http://localhost/docs/broadcast` in your browser. All your `ShouldBroadcast` events are already documented! diff --git a/docs/usage.md b/docs/usage.md index cb5d402..b739275 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -21,7 +21,7 @@ class UserRegistered implements ShouldBroadcast /** @var array */ public array $permissions ) {} - + // ... } ``` From 539a986ffe00ad753c16322beeba5544f6d4b089 Mon Sep 17 00:00:00 2001 From: "Victor M. Gomes" Date: Tue, 28 Jul 2026 19:36:02 -0300 Subject: [PATCH 2/4] docs: improve phrasing for schema integration and add spacing to quick start --- docs/index.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index a61d1e9..9f74a4d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,9 +20,12 @@ features: - title: Zero-Effort Documentation details: Stop maintaining manual AsyncAPI files. Document your events automatically using static code analysis. - title: 🔗 Schema Integration - details: Automatically extracts payload schemas from DTOs or models, ensuring your documentation always matches your code. + details: The broadcasting implementation structure, including data types, is inferred automatically to ensure your documentation always matches your code. --- + +
+ # 🚀 Quick Start ## 1. Install the package From 1ca4cab287ae679eaa154f2a8dd084ad663c9d45 Mon Sep 17 00:00:00 2001 From: "Victor M. Gomes" Date: Tue, 28 Jul 2026 19:46:22 -0300 Subject: [PATCH 3/4] docs: streamline quick start and remove attribute mentions --- README.md | 49 ++++++++-------------------- docs/installation-and-quick-start.md | 43 ++++++------------------ docs/introduction.md | 12 +++---- 3 files changed, 29 insertions(+), 75 deletions(-) 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/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]`. From 1002ccf68b7b7c33d8d06a91fea2869b40e0893e Mon Sep 17 00:00:00 2001 From: "Victor M. Gomes" Date: Tue, 28 Jul 2026 20:13:51 -0300 Subject: [PATCH 4/4] docs: add upgrading guide for v2 --- docs/UPGRADING.md | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) 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).