Principio: "An API is only as good as its documentation."
::: info
La documentazione delle interfacce di comunicazione definisce come i diversi moduli del sistema "parlano" tra loro. Utilizziamo standard aperti per generare documentazione interattiva che permetta di testare le chiamate senza scrivere codice client.
:::
OpenAPI è il linguaggio standard per descrivere le REST API. Permette di definire endpoint, parametri di input, schemi di risposta e metodi di autenticazione.
Uno dei maggiori vantaggi di FastAPI (Python) è la generazione automatica dello schema OpenAPI partendo dai modelli Pydantic.
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Device(BaseModel):
id: int
name: str
status: str = "offline"
@app.post("/devices/", status_code=201)
async def create_device(device: Device):
"""
Registra un nuovo dispositivo IoT nel sistema.
- **id**: Identificativo univoco hardware
- **name**: Nome mnemonico del dispositivo
- **status**: Stato iniziale (default: offline)
"""
return device
/docs (Swagger UI) o /redoc.Mentre OpenAPI gestisce il paradigma "Richiesta/Risposta", AsyncAPI è lo standard per i sistemi basati su messaggi (Publish/Subscribe), come quelli che utilizzano MQTT (fondamentale per Home Assistant e Zigbee2MQTT).
tele/sonoff/SENSOR).# Esempio concettuale di AsyncAPI per MQTT
channels:
home/livingroom/temperature:
publish:
message:
payload:
type: object
properties:
temp:
type: number
humidity:
type: number
/api/v1/devices). Questo evita di "rompere" i client esistenti quando effettui modifiche strutturali.200 OK: Successo.201 Created: Risorsa creata con successo.400 Bad Request: Errore di validazione input.401 Unauthorized: Autenticazione mancante.404 Not Found: Risorsa inesistente.API-Key, OAuth2 o JWT Token.Ultimo aggiornamento: {{UPDATE_DATE}} | Tags: #OpenAPI #Swagger #FastAPI #AsyncAPI #MQTT #REST