docs: update generator-template.md for AsyncAPI v3 parser usage

apps/generator/docs/generator-template.md

@@ -9,7 +9,7 @@ Suppose you can only sleep when the AC in your bedroom is set to 22 °C, and you
 
 In this tutorial:
 
-- You'll use the [Eclipse Mosquito](https://test.mosquitto.org) **MQTT broker**, which you'll connect to subscribe and publish messages using an MQTT client.
+- You'll use the [Eclipse Mosquitto](https://test.mosquitto.org) **MQTT broker**, which you'll connect to subscribe and publish messages using an MQTT client.
 - You'll use [Python Paho-MQTT](https://pypi.org/project/paho-mqtt/) as the **MQTT client** in this project.
 - You'll create a React template that will use the MQTT broker to allow you to monitor your bedroom's temperature and notify you when the temperature drops or rises above 22 °C.
 - Lastly, create a reusable component for the output code's `sendTemperatureDrop` and `sendTemperatureRise` functions.
@@ -39,45 +39,64 @@ Before you begin, make sure you have the following set up:
 
 ## Background context
 
-There is a list of [community maintained templates](https://www.asyncapi.com/docs/tools/generator/template#generator-templates-list), but what if you do not find what you need? In that case, you'll create a user-defined template that generates custom output from the generator.
-Before you create the template, you'll need to have an [AsyncAPI document](https://www.asyncapi.com/docs/tools/generator/asyncapi-document) that defines the properties you want to use in your template to test against. In this tutorial, you'll use the following template saved in the **test/fixtures/asyncapi.yml** file in your template project directory.
+**This tutorial focuses on code generation using templates — not full AsyncAPI document modeling.**
 
-``` yml
+There is a list of [community maintained templates](https://www.asyncapi.com/docs/tools/generator/template#generator-templates-list), but what if you do not find what you need? In that case, you'll create a user-defined template that generates custom output from the generator.
+Before you create the template, you'll need an [AsyncAPI document](https://www.asyncapi.com/docs/tools/generator/asyncapi-document) that defines the properties used in your generator.
+In this tutorial, we use a simplified AsyncAPI document focused on extracting data for template generation.
+You'll use the following document saved as test/fixtures/asyncapi.yml.
 
-asyncapi: 2.6.0
+> 🧭 **Note on AsyncAPI v3 semantics:**  
+> In AsyncAPI v3, the meaning of `publish` and `subscribe` has changed from v2. Now, `action: send` under the top-level `operations` object indicates that the application is publishing (i.e., sending) the message. This tutorial uses that new approach.
 
+```yaml
+asyncapi: "3.0.0"
 info:
   title: Temperature Service
   version: 1.0.0
-  description: This service is in charge of processing all the events related to temperature.
+  description: Service that emits temperature changes from a bedroom sensor.
 
 servers:
   dev:
     url: test.mosquitto.org #in case you're using local mosquitto instance, change this value to localhost.
     protocol: mqtt
 
 channels:
-  temperature/changed:
-    description: Updates the bedroom temperature in the database when the temperatures drops or goes up.
-    publish:
-      operationId: temperatureChange
-      message:
-        description: Message that is being sent when the temperature in the bedroom changes.
+  temperatureChanged:
+    address: temperature/changed
+    messages:
+      temperatureChange:
+        description: Message sent when the temperature in the bedroom changes.
         payload:
-          type: object
-          additionalProperties: false
-          properties:
-            temperatureId:
-              type: string
+          $ref: '#/components/schemas/Temperature' # refactored from inline payload for better reuse
+
+operations:
+  sendTemperatureChanged:
+    action: send
+    summary: Temperature changes are pushed to the broker
+    channel:
+      $ref: '#/channels/temperatureChanged'
+
 components:
   schemas:
-    temperatureId:
+    Temperature:
       type: object
       additionalProperties: false
       properties:
-        temperatureId:
+        value:
+          type: number
+        unit:
           type: string
+
 ```
+> 🛠️ **Note on Payload Schema Refactor:**  
+> In this version, the payload definition has been moved to a reusable schema component (#/components/schemas/Temperature). This change reflects AsyncAPI v3 best practices, but doesn't affect functionality. This aligns with AsyncAPI v3's best practices for reuse and separation of concerns. The payload was also updated to include a unit field (e.g., °C, °F) to better reflect real-world temperature data. While this introduces a slight schema expansion, it enhances clarity for generated code consumers. The value field replaces the previous temperatureId for clearer semantics.
+
+> 🆕 This document uses the AsyncAPI 3.0.0 structure. Notable changes include `operations` now being top-level and the use of `address:` in `channels` instead of nested publish/subscribe.
+## Handling Diagnostics (Warnings)
+
+When using the latest AsyncAPI parser, it's important to handle not just errors, but also diagnostics (warnings). These help identify non-critical issues, such as missing recommended fields like `license`, `contact`, or outdated spec versions.
+
 
 ## Overview of steps
 
@@ -100,7 +119,7 @@ python-mqtt-client-template
 └── package.json
 ```
 
-Lets break it down:
+Let's break it down:
 
 ### package.json file
 
@@ -649,4 +668,4 @@ Great job completing this tutorial! You have learnt how to use an AsyncAPI file
 
 If you want to tinker with a completed template and see what it would look like in production, check out the [Paho-MQTT template](https://github.com/derberg/python-mqtt-client-template/tree/v1.0.0). You can also check out the accompanying [article about creating MQTT client code](https://www.brainfart.dev/blog/asyncapi-codegen-python).
 
-You can also check out the [MQTT beginners guide](https://medium.com/python-point/mqtt-basics-with-python-examples-7c758e605d4) tutorial to learn more about asynchronous messaging using MQTT.
+You can also check out the [MQTT beginners guide](https://medium.com/python-point/mqtt-basics-with-python-examples-7c758e605d4) tutorial to learn more about asynchronous messaging using MQTT.