OpenAPI e Swagger (1): che cos'è OpenAPI e la differenza con Swagger

Giovanni Pace

Descrizione

OpenAPI e Swagger non sono la stessa cosa: OpenAPI è lo standard, una specifica aperta per descrivere le API HTTP in JSON o YAML, mentre Swagger è l'ecosistema di strumenti che la usa. Partiamo da uno scenario reale, il collega che ha finito il backend e ti passa solo GET /api/courses, per capire perché a chi sviluppa il frontend serve un contratto API.

Cosa imparerai

  • Perché un endpoint senza documentazione costringe il frontend a tirare a indovinare
  • Le domande tipiche: cosa restituisce, quali campi sono obbligatori, che errori arrivano (404 e altri)
  • Che cos'è un contratto API tra backend developer e frontend developer
  • Che cos'è la specifica OpenAPI (OAS), la versione 3.2 e i formati JSON e YAML
  • Swagger UI per visualizzare e invocare le API, Swagger Editor per scriverle e validarle
  • SpringDoc OpenAPI per generare la documentazione in Spring Boot