Sommario

    Creare una documentazione Swagger per PHP

    Creato il 10/12/2025 Aggiornato il 12/12/2025 Categorie PHP

    Swagger è un insieme di strumenti open-source, basati sulla specifica OpenAPI, per consentire agli sviluppatori di documentare in modo chiaro le funzionalità di una REST API attraverso la creazione automatica di documentazione web interattiva.

    Con questo articolo si vedrà come documentare un servizio dati REST creato con PHP.

    1. Inizialmente effettueremo il download della libreria zircote/swagger-php.
    2. Con quest’ultima saremo in grado di generare un file JSON (o YAML) a partire da particolari annotazioni inserite nel codice sorgente.
    3. Il file generato sarà successivamente utilizzato da Swagger UI per creare una documentazione web interattiva che non solo descriverà dettagliatamente il funzionamento delle API (endpoint, parametri, tipi di dati, criteri di sicurezza) ma permetterà anche di testarle evitando l’uso di altri strumenti come Postman.

    Procediamo passo dopo passo.

    Prerequisiti

    Per cominciare è sufficiente creare un progetto PHP 8.1+ con Composer come gestore di dipendenze. Si dà per scontata inoltre, considerato l’argomento, una conoscenza quantomeno di massima dei principi architetturali REST e un servizio dati da dover documentare o l’intenzione di scriverne uno a breve.

    Installare swagger-php

    Dal terminale di comando, assicurarsi innanzitutto di essere nella cartella del nostro progetto, eventualmente usare cd per spostarsi nella cartella in cui è presente il file composer.json. A questo punto per installare la libreria swagger-php eseguire il comando:

    composer require zircote/swagger-php

    Se si usa Visual Studio Code, dopo avere aperto il progetto, premere CTRL+J per aprire il terminale integrato già impostato sulla directory del progetto.

    Aggiornare il codice

    Aggiungere nel proprio codice sorgente degli attributi PHP ad hoc. Questi saranno convertiti successivamente in un file JSON (o YAML) dalla libreria che abbiamo appena incluso nel progetto.

    Gli attributi in PHP (introdotti da PHP 8) sono metadati strutturati che si aggiungono a classi, metodi, funzioni, proprietà e costanti per fornire informazioni che sostituiscono le vecchie annotazioni basate su commenti.

    Si prenderanno come esempio i seguenti attributi proposti nella documentazione.

    Aggiungere pertanto, come nell'esempio sopra, l’attributo OA\Info in prossimità di una classe e gli attributi OA\Get e OA\Response in prossimità di un metodo delle nostre API. Non dimenticare la prima riga use OpenApi\Attributes as OA; che importa il namespace OA. Questi sono gli attributi minimi richiesti e, come è evidente, hanno la seguente struttura #[OA\Attribute(props)].

    Non mancano nella guida utente della libreria esempi d'uso più interessanti e meno elementari da cui prendere spunto per scrivere una documentazione completa. Può tornare utile inoltre la descrizione dettagliata di tutti gli attributi disponibili. Includere nel proprio codice gli attributi dell’esempio suddetto è comunque utile per cominciare e per accertarsi che il nostro ambiente di sviluppo sia configurato a dovere.

    Generare il file JSON

    Creare quindi, per comodità, la cartella docs in cui verrà generata la documentazione e aggiungere al suo interno il file json.php con le seguenti linee di codice:

    Questo codice genererà il file JSON a partire dagli attributi che abbiamo aggiunto nel punto precedente. Questo file JSON, a sua volta, e così come abbiamo già accennato in precedenza, sarà utilizzato per generare la nostra documentazione interattiva con Swagger UI.

    Possiamo testare subito che il file funzioni come ci si aspetta puntando ad esso con il browser. Dovrebbe restituire queste poche righe JSON:

    {
    "openapi": "3.0.0",
    "info": {
        "title": "My First API",
        "version": "0.1"
    },
    "paths": {
        "/api/data.json": {
            "get": {
                "operationId": "getData",
                "responses": {
                    "200": {
                        "description": "The data"
                    }
                }
            }
        }
    }
}

    Se invece viene mostrato qualche errore è molto probabile che non si siano impostati correttamente gli indirizzamenti (le stringhe path-to nel codice sopra) al file autoload.php o al nostro progetto nelle prime righe del codice. La pagina FAQ della guida utente inoltre fornisce la soluzione ai problemi comuni che si potrebbero riscontrare in questa fase.

    Utilizzare Swagger UI

    Arrivati a questo punto ricapitoliamo brevemente i passaggi precedenti. Abbiamo aggiunto delle annotazioni particolari al nostro codice da cui abbiamo ricavato, tramite la libreria swagger-php, un file JSON che descrive in base allo standard OpenAPI il nostro servizio dati REST. Se tuttavia non ci fosse uno strumento che convertisse tutto ciò in una documentazione web interattiva di questo file ce ne faremmo ben poco.

    Dal terminal allora scarichiamo Swagger UI nel nostro progetto con il comando:

    git clone https://github.com/swagger-api/swagger-ui.git

    In alternativa è possibile scaricare il pacchetto con il browser direttamente da Github. Il link è annidato in un menu a tendina dentro il pulsante Code come si può vedere nell’immagine sotto.

    Copiare la cartella dist del pacchetto scaricato all’interno della nostra cartella docs e rinominarla swagger. Quest’ultima operazione è ovviamente opzionale così come è opzionale eliminare la cartella swagger-ui dopo aver copiato quello che ci interessa.

    Editare infine il file swagger-initializer.js dentro la cartella swagger (o dist se il nome è rimasto invariato) cambiando l’URL del file JSON. Nel nostro caso, poiché la sia la cartella swagger sia il file json.php (che genera il file JSON) sono all’interno della stessa cartella docs, sarà sufficiente impostare l’indirizzo relativo ../json.php.

    Fatto anche quest'ultimo passaggio abbiamo terminato! Non resta che puntare con il browser alla cartella swagger/index.html per visualizzare la nostra documentazione che, per il momento, è davvero essenziale.

    Conclusioni finali

    Swagger è lo standard per scrivere una documentazione efficace per le proprie API REST. Nella guida utente, ora che si è capito come configurare tutto, si troveranno numerosi spunti per scrivere una documentazione completa per il proprio lavoro.

    Devo ammettere che non è stato immediato comprendere come ottenere lo scopo per carenze di documentazione sul web. È stato fondamentale questo video tutorial che, sebbene datato di ben 5 anni (al momento in cui scrivo), mi ha permesso di conoscere tutti i passaggi necessari e riproporli aggiornando soltanto qualche dettaglio.