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
Successive: 3.0.3 (2020), 3.1.0 (2021 — allineamento completo JSON Schema 2020-12), 3.2.0 (in draft).
Esempio
openapi: 3.0.3
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 drift rischia
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)
Le Linee Guida di interoperabilità AgID (2020+) specificano OpenAPI 3.0 come formato obbligatorio per le API delle pubbliche amministrazioni italiane.
Riferimenti: OpenAPI 3.0 (26 luglio 2017). OpenAPI Initiative (Linux Foundation). Donato da SmartBear (2015). OpenAPI 3.1.0 (2021) allineato a JSON Schema 2020-12. Tool Swagger UI, ReDoc, OpenAPI Generator. Linee Guida AgID interoperabilità richiedono OpenAPI 3.0.