Generate Swagger/OpenAPI documentation with paths, schemas, and authentication definitions. Part of the DevTools Surf developer suite. Browse more tools in the API / Config collection.
Use Cases
Generate OpenAPI documentation for a new REST API from endpoint descriptions and request/response examples.
Document an existing undocumented API by generating a skeleton spec and adding details incrementally.
Create a machine-readable API contract for use with code generators (TypeScript clients, mock servers).
Produce interactive API documentation that developers can test without leaving the browser.
Tips
Define $ref schema components for shared request/response objects — repeating inline schema definitions causes OpenAPI specs to diverge when schema changes are made in only some places.
Include example values in schema definitions — tools like Swagger UI use them for live try-it-out requests and documentation previews.
Add operationId to every endpoint — without them, code generators produce ambiguous function names, making generated client code harder to use.
Fun Facts
The Swagger specification was created by Tony Tam at Wordnik in 2011 to auto-generate API documentation for the Wordnik API. It was donated to the OpenAPI Initiative in 2015 and renamed to OpenAPI Specification.
OpenAPI 3.0 (2017) was a major breaking change from Swagger 2.0 — introducing components, callbacks, and links while removing a number of Swagger 2.0 constructs. Migration tools exist but the specs are not directly compatible.
The OpenAPI Specification repository on GitHub has over 26,000 stars and is one of the most-forked API specification repositories, reflecting its adoption as a de facto standard across the industry.
FAQ
OpenAPI 3.0 vs. Swagger 2.0 — which should I use?
OpenAPI 3.1 (2021) for new projects — it is the current standard with full JSON Schema compatibility. OpenAPI 3.0 is a safe choice with broader tool support. Swagger 2.0 is legacy; only use it if existing tooling requires it.
Can I auto-generate an OpenAPI spec from existing code?
Yes — many frameworks have libraries that generate OpenAPI specs from code annotations: Springdoc (Java Spring), Swashbuckle (ASP.NET), and drf-spectacular (Django REST Framework). This produces a spec that stays in sync with the code.
