People say "Swagger" and "OpenAPI" like they're two different things. Here's the actual story.
Swagger came first. It was a spec plus tooling for describing REST APIs. It got so popular the spec was donated to a foundation and renamed OpenAPI. So today, "Swagger" sometimes means the old spec, sometimes the tools, and sometimes just OpenAPI out of habit.
The practical bit: if you have a Swagger file, it's almost certainly OpenAPI-compatible, and you can turn it into docs the same way.
Swagger to Markdown handles either: https://markdown.co.in/tools/swager-to-markdown.html
The bigger lesson from this week: if a machine-readable version of your API already exists in any form, you should almost never write docs from scratch. Generate first, polish second.
One tiny tip: pick one name, Swagger or OpenAPI, and use it consistently across your team. Saves new folks a surprising amount of confusion.
Top comments (0)