docs: Add SignalR hub documentation with events and connection examples

Author: aalmada

src/ApiService/BookStore.ApiService/Infrastructure/OpenApiTransformerExtensions.cs

@@ -87,6 +87,61 @@ static string BuildApiDescription()
             - Multi-language support (English, Portuguese, Spanish, French, German)
             - Request tracking with correlation IDs
             - Optimistic concurrency control for updates
+            - Real-time notifications via SignalR
+
+            ## SignalR Hub
+
+            **WebSocket Endpoint**: `/hub/bookstore`
+
+            ### Events (Server → Client)
+
+            The server broadcasts the following events to all connected clients:
+
+            - **BookCreatedNotification** - Sent when a book is created
+              ```json
+              {
+                "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+                "title": "Clean Code",
+                "eventType": "BookCreated",
+                "timestamp": "2025-12-28T16:00:00Z"
+              }
+              ```
+
+            - **BookUpdatedNotification** - Sent when a book is updated
+            - **BookDeletedNotification** - Sent when a book is deleted
+
+            ### Connection Example
+
+            **JavaScript/TypeScript**:
+            ```javascript
+            const connection = new signalR.HubConnectionBuilder()
+                .withUrl("/hub/bookstore")
+                .withAutomaticReconnect()
+                .build();
+
+            connection.on("BookCreatedNotification", (notification) => {
+                console.log("Book created:", notification);
+            });
+
+            await connection.start();
+            ```
+
+            **C# (.NET)**:
+            ```csharp
+            var connection = new HubConnectionBuilder()
+                .WithUrl("https://localhost:7001/hub/bookstore")
+                .WithAutomaticReconnect()
+                .Build();
+
+            connection.On<BookNotification>("BookCreatedNotification", notification =>
+            {
+                Console.WriteLine($"Book created: {notification.Title}");
+            });
+
+            await connection.StartAsync();
+            ```
+
+            For more details, see the [SignalR Guide](https://github.com/yourusername/bookstore/blob/main/docs/signalr-guide.md).
             """;
     }
 }