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
Further releases are on the OpenAPI Initiative roadmap.
Example
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 — 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’s regulatory path and PA interoperability are moving toward an explicit requirement of OpenAPI as the format for public APIs.
References: OpenAPI 3.0 (26 July 2017). OpenAPI Initiative (Linux Foundation). Donated by SmartBear (2015). Swagger UI, ReDoc, OpenAPI Generator tools.