IT 
EN Web Services Documentation è un’estensione Joomla che fornisce documentazione API interattiva direttamente nell’area amministrativa di Joomla. È pensata per aiutare gli sviluppatori a esplorare, comprendere e testare i web services di Joomla tramite Swagger UI e Redoc con specifiche OpenAPI generate automaticamente.
Panoramica
Web Services Documentation è un sistema completo di documentazione API per Joomla 6.0+ che fornisce documentazione interattiva tramite Swagger UI e Redoc, con generazione automatica di specifiche OpenAPI 3.1.0 basata sui componenti Joomla installati.
È pensato per sviluppatori che realizzano integrazioni, testano endpoint o documentano estensioni Joomla con API personalizzate. Il progetto punta su integrazione nativa nel backend Joomla, navigazione strutturata, supporto per autenticazione e un’esperienza d’uso chiara e orientata allo sviluppo.
Documentazione API interattiva
Swagger UI consente di esplorare e testare gli endpoint API direttamente dall’ambiente amministrativo di Joomla.
Vista di lettura professionale
Redoc offre un’interfaccia pulita, strutturata e molto leggibile, con ricerca e navigazione integrate.
Generazione automatica
L’estensione può generare automaticamente specifiche OpenAPI analizzando componenti installati e route basate su plugin.
Requisiti
La scheda pubblica dell’estensione descrive Web Services Documentation come un’estensione Joomla gratuita compatibile con Joomla 6 e pensata per la documentazione delle API all’interno dell’area amministrativa. Il pacchetto include un componente e un modulo per il menu Help, che insieme espongono le viste di documentazione e i collegamenti rapidi nel backend.
| Requisito | Dettaglio | Note |
|---|---|---|
| Joomla | Joomla 6 | La scheda JED indica compatibilità con Joomla 6. |
| Tipi di estensione | Componente e modulo | Il pacchetto include sia un componente sia un modulo. |
| Accesso backend | Area amministrativa | Le interfacce di documentazione sono integrate direttamente nel backend Joomla. |
| Sito con API attive | Utile quando i web services Joomla sono disponibili | L’estensione è particolarmente utile quando devi ispezionare o testare gli endpoint API disponibili. |
Ideale per
- Esplorazione API
- Onboarding sviluppatori
- Documentazione componenti custom
- Testing endpoint
- Workflow backend per developer
Come funziona
Web Services Documentation analizza i componenti Joomla installati e le route API basate su plugin, quindi costruisce specifiche OpenAPI 3.1.0 che possono essere mostrate attraverso diverse interfacce di documentazione. Supporta sia l’esplorazione interattiva sia una consultazione più orientata alla lettura, a seconda dell’interfaccia scelta.
Workflow tipico
- Installa il pacchetto dell’estensione nel backend di Joomla.
- Apri l’area Help dell’amministrazione.
- Scegli Documentation, Swagger oppure Redoc dai link presenti nella card dedicata.
- Carica una specifica statica o generata dinamicamente.
- Consulta endpoint, autenticazione, parametri e risposte.
Esplorazione API interattiva
Swagger UI rappresenta la vista interattiva del progetto e permette agli sviluppatori di ispezionare le operazioni, controllare struttura di richieste e risposte e testare gli endpoint in un workflow guidato dalla documentazione.
Accesso dal menu Help
L’accesso a Swagger e Redoc avviene dal menu Help del backend Joomla, utilizzando i link presenti nella card dedicata. In questo modo la documentazione è facile da raggiungere direttamente dall’area amministrativa, senza dover ricordare URL personalizzati o punti di accesso separati.
Come aprirlo
- Accedi all’area amministrativa di Joomla.
- Apri il menu Help.
- Individua la card aggiunta da Web Services Documentation.
- Fai clic sul collegamento Swagger, Redoc oppure sulla vista principale della documentazione.
- Inizia a consultare le interfacce di documentazione API disponibili.
Integrazione nel menu Help del backend
Il pacchetto include un modulo dedicato al menu Help che aggiunge pulsanti di accesso rapido alle diverse viste della documentazione direttamente nell’amministrazione Joomla.
Opzioni della specifica
L’estensione fornisce tre modalità di specifica: una specifica statica pre-generata delle API core di Joomla, una specifica generata dinamicamente in base ai plugin attivi e una specifica più ampia che include tutti i componenti installati. Questo offre agli sviluppatori una scelta pratica tra documentazione di riferimento stabile e una documentazione più aderente allo stato reale dell’installazione Joomla.
| Specifica | Cosa include | Ideale per |
|---|---|---|
| Static Spec | API core Joomla pre-generate | Documentazione di riferimento stabile. |
| Generated (Active Plugins) | Specifica dinamica basata sui plugin attivi | Ispezione dell’ambiente effettivamente in uso. |
| Generated (All Components) | Specifica completa con i componenti installati | Copertura più ampia e analisi estesa delle API. |
Perché è utile
Team diversi hanno esigenze diverse in termini di visibilità delle API. Le specifiche statiche sono utili per la coerenza, mentre quelle generate sono migliori quando serve una documentazione che rispecchi lo stato reale dell’installazione Joomla.
Funzionalità
La pagina pubblica dell’estensione evidenzia come funzionalità principali le doppie interfacce di documentazione, la generazione automatica OpenAPI, la navigazione gerarchica, il supporto alla modalità scura, la gestione dell’autenticazione e l’integrazione nel backend.
Swagger UI
Esploratore API interattivo con test live, esempi di richieste e risposte e supporto integrato all’autorizzazione.
Redoc
Vista documentale professionale con layout strutturato, ricerca, navigazione persistente e supporto dark mode.
OpenAPI automatico
Genera specifiche OpenAPI 3.1.0 a partire da componenti installati, route e API basate su plugin.
Navigazione gerarchica
Organizza la documentazione tramite una gerarchia di tag per facilitare la consultazione di API estese.
Swagger UI
Swagger è l’interfaccia più interattiva ed è particolarmente utile quando vuoi analizzare i dettagli degli endpoint, controllare gli schemi e provare richieste autenticate rimanendo in un workflow guidato dalla documentazione.
Redoc
Redoc è l’interfaccia più pulita e orientata alla consultazione, ideale quando vuoi un’esperienza di lettura più lineare e una navigazione più comoda tra API di grandi dimensioni.
Autenticazione
L’estensione include supporto all’autenticazione basata su token, con generazione automatica dei token API e riutilizzo integrato nei flussi di autorizzazione di Swagger UI. Secondo la descrizione del progetto, i token vengono gestiti in modo sicuro nell’ambiente Joomla e i controlli di permesso sono applicati lungo l’intero workflow.
Gestione automatica token
I token possono essere generati e riutilizzati automaticamente per utenti esistenti nei workflow supportati.
Autorizzazione in Swagger
L’autenticazione si integra con l’interfaccia Swagger UI per rendere più semplice il test degli endpoint protetti.
Controlli di permesso
La descrizione del progetto evidenzia una corretta validazione dei permessi lungo tutto il flusso dell’estensione.
Memorizzazione sicura
I dati dei token API vengono gestiti nell’ambiente Joomla e non tramite un servizio esterno.
Riferimento utile
Per un contesto più ampio sulle API core di Joomla e sugli endpoint disponibili, può essere utile consultare anche la documentazione ufficiale di Joomla: Joomla Core APIs.
Casi d’uso
- Esplorare gli endpoint API disponibili in Joomla in modo strutturato.
- Testare richieste autenticate tramite un’interfaccia interattiva.
- Documentare componenti Joomla con API personalizzate per uso interno o di team.
- Aiutare gli sviluppatori a comprendere parametri, filtri, risposte e pattern delle route.
- Migliorare i workflow backend con accesso più rapido alla documentazione API.
- Supportare l’onboarding di sviluppatori nuovi ai web services di Joomla.
Perché usarlo
Le API Joomla sono molto più facili da comprendere quando route, parametri, autenticazione e strutture di risposta sono visibili in un unico punto. Questa estensione porta tutta questa visibilità direttamente nel backend amministrativo e rende la documentazione molto più pratica per il lavoro di sviluppo reale.
Risoluzione problemi
I link Swagger o Redoc non compaiono
Controlla che il modulo del menu Help sia installato, abilitato e visibile nel backend amministrativo di Joomla.
La specifica generata sembra incompleta
Verifica se stai usando la specifica statica, quella dei plugin attivi oppure quella di tutti i componenti, perché ogni opzione espone un perimetro diverso.
Il test autenticato non funziona
Assicurati che i token API siano disponibili e che l’utente corrente abbia i permessi richiesti per gli endpoint che stai testando.
Una route non compare nella documentazione
Verifica se la route proviene da un componente installato, da un plugin abilitato o da un’integrazione API personalizzata non esposta nella modalità di specifica selezionata.
Il punto di accesso nel backend è difficile da trovare
Usa il menu Help dell’amministrazione Joomla e apri i link presenti nella card dedicata fornita dall’estensione.
Servono dettagli più approfonditi sulle API Joomla
Usa anche la documentazione ufficiale Joomla Core APIs come riferimento per endpoint di esempio, formati di richiesta e copertura API più ampia.