A cosa serve Swagger?

Swagger (ora Specifica OpenAPI) viene utilizzato per descrivere, documentare e visualizzare le API RESTful. Questo permette a sviluppatori, tester e consumatori di API di comprendere le funzionalità del servizio senza accesso al codice sorgente.

Funzioni principali:

1. Documentazione: Creazione automatica di documentazione interattiva dell'API.
2. Sviluppo: Aiuta nello sviluppo dell'API fornendo una definizione chiara del contratto.
3. Test: L'interfaccia Swagger (Swagger UI) permette di testare direttamente i punti finali dell'API dal browser.
4. Generazione di codice: È possibile generare codice client (SDK) o stub di server basati sulla specifica OpenAPI.
5. Design: Può essere usato come strumento per progettare l'API prima di iniziare a codificare (Approccio Design-First).

Esempio di frammento di specifica in formato YAML:

# Breve descrizione dell'API
openapi: 3.0.0
info:
  title: La mia API di test
  version: 1.0.0
paths:
  /items:
    get:
      summary: Ottieni l'elenco di tutti gli elementi
      responses:
        '200':
          description: Elenco degli elementi ottenuto con successo
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Item'
components:
  schemas:
    Item:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string

Questo garantisce coerenza tra le diverse parti coinvolte nello sviluppo e nell'uso dell'API.