From Swagger to OpenAPI
Swagger was born in 2010 as Tony Tam’s toolkit (Wordnik) to describe REST APIs in a machine-readable way. In 2015 SmartBear acquires Swagger and donates the spec to OpenAPI Initiative (Linux Foundation). Spec v2.0 (Swagger 2.0) is renamed OpenAPI 2.0 in 2015.
The 3.0 release
OpenAPI 3.0 is published on 26 July 2017. Major improvements:
- Components — reusable schemas/parameters/responses
- Callbacks and links for async and HATEOAS
- Better security — OAuth2 flows, OpenID Connect
- Improved content negotiation
- JSON Schema-based schema
Subsequent: 3.0.3 (2020), 3.1.0 (2021 — full alignment with JSON Schema 2020-12), 3.2.0 (in draft).
Example
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 — auto-generated interactive documentation
- ReDoc — alternative UI
- Swagger Editor — YAML IDE
- OpenAPI Generator — generates client/server in 50+ languages
- Prism — mock server from spec
- Dredd, Schemathesis — contract testing
- Spectral — OpenAPI linting
Framework integration
- FastAPI (Python) — automatically generates OpenAPI from type hints
- NestJS (TS) —
@ApiProperty()decorators - Spring Boot — springdoc-openapi
- Go — echo-swagger, oapi-codegen
- ASP.NET Core — Swashbuckle
Many modern frameworks generate OpenAPI from code (code-first) instead of writing it by hand (spec-first).
Design-first vs Code-first
- Design-first — write the spec, then implement; binding contract between teams
- Code-first — generate the spec from code; fast but drift risk
Large public APIs (Stripe, GitHub, Twilio) use design-first with spec review.
In the Italian context
OpenAPI is standard in:
- Digital PA APIs — PagoPA, Interoperability (former DAF), AgID Guidelines require it
- PSD2 Banking — European regulations specify OpenAPI as format
- Italian API marketplaces
- Corporate API gateways (Kong, Apigee, Tyk, AWS API Gateway)
AgID Interoperability Guidelines (2020+) specify OpenAPI 3.0 as the mandatory format for Italian public administration APIs.
References: OpenAPI 3.0 (26 July 2017). OpenAPI Initiative (Linux Foundation). Donated by SmartBear (2015). OpenAPI 3.1.0 (2021) aligned with JSON Schema 2020-12. Swagger UI, ReDoc, OpenAPI Generator tools. AgID interoperability guidelines require OpenAPI 3.0.