Da Swagger a OpenAPI
Swagger nasce nel 2010 come toolkit di Tony Tam (Wordnik) per descrivere API REST in modo machine-readable. Nel 2015 SmartBear acquisisce Swagger e dona lo spec alla OpenAPI Initiative (Linux Foundation). Spec v2.0 (Swagger 2.0) è rinominata OpenAPI 2.0 nel 2015.
Il rilascio 3.0
OpenAPI 3.0 è pubblicato il 26 luglio 2017. Grandi miglioramenti:
- Components — schema/parameter/response riusabili
- Callbacks e links per async e HATEOAS
- Better security — OAuth2 flows, OpenID Connect
- Content negotiation migliorato
- Schema JSON Schema-based
Release successive in roadmap sotto OpenAPI Initiative.
Esempio
openapi: 3.0.0
info: { title: Users API, version: 1.0 }
paths:
/users/{id}:
get:
parameters:
- in: path
name: id
schema: { type: string }
responses:
'200':
content:
application/json:
schema: { $ref: '#/components/schemas/User' }
components:
schemas:
User:
type: object
properties:
id: { type: string }
name: { type: string }Tooling
- Swagger UI — documentazione interattiva auto-generata
- ReDoc — alternativa UI
- Swagger Editor — IDE YAML
- OpenAPI Generator — genera client/server in 50+ linguaggi
- Prism — mock server da spec
- Dredd, Schemathesis — testing contract
- Spectral — linting OpenAPI
Integrazione framework
- FastAPI (Python) — genera OpenAPI da type hints automaticamente
- NestJS (TS) — decoratori
@ApiProperty() - Spring Boot — springdoc-openapi
- Go — echo-swagger, oapi-codegen
- ASP.NET Core — Swashbuckle
Molti framework moderni generano OpenAPI dal codice (code-first) invece di scriverlo a mano (spec-first).
Design-first vs Code-first
- Design-first — scrivi la spec, poi implementi; contratto binding tra team
- Code-first — genera la spec dal codice; rapido ma rischia drift
Le grandi API pubbliche (Stripe, GitHub, Twilio) usano design-first con review della spec.
Nel contesto italiano
OpenAPI è standard in:
- API PA digitale — PagoPA, Interoperabilità (ex DAF), Linee Guida AgID lo richiedono
- Banking PSD2 — regolatorie europee specificano OpenAPI come formato
- API marketplace italiani
- API gateway aziendali (Kong, Apigee, Tyk, AWS API Gateway)
Il percorso regolatorio di AgID e l’interoperabilità PA stanno muovendo verso la richiesta esplicita di OpenAPI come formato per le API pubbliche.
Riferimenti: OpenAPI 3.0 (26 luglio 2017). OpenAPI Initiative (Linux Foundation). Donato da SmartBear (2015). Tool Swagger UI, ReDoc, OpenAPI Generator.