🚀 Introduzione

Zen Generator è un tool open-source progettato per semplificare la generazione di codice Python a partire da specifiche AsyncAPI e per ottenere specifiche AsyncAPI da codice Python esistente. Il suo obiettivo è automatizzare la creazione di componenti per architetture a microservizi basate su messaggistica, riducendo il lavoro manuale e garantendo coerenza tra implementazione e documentazione.

📌 Cos’è AsyncAPI?

AsyncAPI è una specifica open-source pensata per definire e documentare API asincrone, analogamente a quanto fa OpenAPI per le API REST.

Viene utilizzata per descrivere il comportamento di sistemi che comunicano tramite eventi e messaggi, come quelli basati su RabbitMQ, Kafka, MQTT e NATS.

Un documento AsyncAPI è scritto in YAML o JSON e contiene informazioni su:
✅ Canali di comunicazione
✅ Messaggi trasmessi
✅ Schemi di dati
✅ Protocolli supportati

Esempio di una specifica AsyncAPI:

asyncapi: 3.0.0
info:
  title: Account Service
  version: 1.0.0
  description: This service is in charge of processing user signups :rocket:
channels:
  userSignedup:
    address: 'user/signedup'
    messages:
      userSignedupMessage:
        $ref: '#/components/messages/UserSignedUp'
operations:
  processUserSignups:
    action: 'receive'
    channel:
      $ref: '#/channels/userSignedup'
components:
  messages:
    UserSignedUp:
      payload:
        type: object
        properties:
          displayName:
            type: string
            description: Name of the user
          email:
            type: string
            format: email
            description: Email of the user

✨ Funzionalità principali

Zen Generator fornisce diverse funzionalità chiave:

🐍 Generazione di codice Python da AsyncAPI: crea automaticamente il codice per produttori e consumatori di messaggi.

🐍 Supporto per Python con type hints: il codice generato utilizza Python tipizzato per una maggiore leggibilità e manutenibilità.

⚡ Generazione di API FastAPI: è possibile generare direttamente applicazioni FastAPI compatibili con AsyncAPI.

🔍 Estrazione di AsyncAPI dal codice: analizza il codice Python e genera la specifica AsyncAPI corrispondente.

📡 Architettura modulare ed estensibile: è possibile personalizzare il processo di generazione per adattarlo a esigenze specifiche.

📦 Installazione

Zen Generator è disponibile come pacchetto Python e può essere installato con:

con uv:

uv tool install zen-generator

con pipx:

pipx install zen-generator

con uvx:

uvx zen-generator

🖥️ Esempi d’uso

🎯 Generare codice da un file AsyncAPI

Per generare codice Python a partire da una specifica AsyncAPI in formato YAML o JSON:

# Generare implementazione FastAPI da specifica AsyncAPI
uvx zen-generator fastapi

# Generare implementazione Python con type hints da specifica AsyncAPI
uvx zen-generator pure-python

# Generare specifica AsyncAPI dal codice Python
uvx zen-generator asyncapi-documentation

Implementazione Python con type hints

# models.py
from __future__ import annotations

from typing import TypedDict


class UserModel(TypedDict):
    id: int
    name: str
    email: str | None = None

#functions.py
from __future__ import annotations

from .models import UserModel

def get_user(user_id: int) -> UserModel:
    ...

Implementazione FastAPI

# models.py
from __future__ annotations

from pydantic import BaseModel

class UserModel(BaseModel):
    id: int
    name: str
    email: str | None = None

# functions.py
from __future__ nnotations

from fastapi import FastAPI

from .models import UserModel

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: int) -> UserModel:
    ...

Generare specifica AsyncAPI dal codice Python

# asyncapi.yaml
asyncapi: 3.0.0
info:
  title: Zen
  version: 0.0.1
  description: ''
channels:
  get_user:
    $ref: '#/components/channels/get_user'
operations:
  get_user:
    $ref: '#/components/operations/get_user'
components:
  channels:
    get_user:
      messages:
        request:
          $ref: '#/components/messages/get_user_request'
        response:
          $ref: '#/components/messages/get_user_response'
  operations:
    get_user:
      action: receive
      description: ''
      channel:
        $ref: '#/channels/get_user'
      messages:
      - $ref: '#/channels/get_user/messages/request'
      reply:
        channel:
          $ref: '#/channels/get_user'
        messages:
        - $ref: '#/channels/get_user/messages/response'
  messages:
    get_user_request:
      title: Request params for get_user
      summary: ''
      description: ''
      payload:
        type: object
        required:
        - user_id
        properties:
          user_id:
            type: integer
            description: ''
    get_user_response:
      title: Response params for get_user
      summary: ''
      description: ''
      payload:
        $ref: '#/components/schemas/UserModel'
        format: required
  schemas:
    UserModel:
      type: object
      base_class: BaseModel
      required:
      - id
      - name
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

❌ Cosa è attualmente supportato e non?

Attualmente, sono supportate solo le definizioni di modelli e funzioni nel blocco components del file AsyncAPI. Le definizioni inline non sono supportate.

⚙️ Il parametro required

Zen Generator introduce il parametro required, che consente di specificare esplicitamente i campi obbligatori in una definizione AsyncAPI.

Esempio:

components:
  messages:
    get_user_request:
      title: Request params for get_user
      summary: ''
      description: ''
      payload:
        type: object
        required:
        - user_id
        properties:
          user_id:
            type: integer
            description: ''
  schemas:
    UserModel:
      type: object
      base_class: BaseModel
      required:
      - user_id
      - name
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

📌 Questa configurazione assicura che il campo user_id e name vengano considerato obbligatorio nel codice generato.

📢 Conclusione

Zen Generator semplifica lo sviluppo e la documentazione di microservizi basati su messaggistica, garantendo coerenza tra implementazione e specifiche AsyncAPI.

✨ Supporto per Python con type hints e FastAPI.
✨ Generazione ed estrazione di AsyncAPI.
✨ Estensibilità e personalizzazione.

📌 Il progetto è open-source e disponibile su GitHub: WaYdotNET/zen-generator. Feedback e contributi sono benvenuti! 🚀

📬 Vuoi rimanere aggiornato?

Seguimi su GitHub e resta aggiornato sulle future evoluzioni del progetto!