Swagger and OpenAPI: The Docs That Write Themselves
"Swagger" and "OpenAPI" get used interchangeably, and untangling that is actually the first useful thing to do here, one is a specification, the other is a tool that renders it. This post uses the Product API from an earlier CRUD post as the running example throughout, since the goal is showing exactly how documentation gets generated from code you've already written, not introducing a new domain…
Swagger and OpenAPI are often used interchangeably, but they serve different purposes. OpenAPI is a specification that describes an API in detail, while Swagger is a tool that renders this specification as an interactive, browsable webpage. OpenAPI is essentially the recipe card for an API, while Swagger UI is the printed menu for customers to view and navigate the API.
To generate documentation from existing code, SwaggerGen is used. This tool reflects over controllers, DTOs, and attributes to produce an OpenAPI document that mirrors the structure of the code. For example, the paths and operations in the OpenAPI document correspond to the routes and HTTP verbs in the controller, while the response schemas come from the ProducesResponseType attributes.
The generated specification is a JSON or YAML document that can be fetched from a specific endpoint, such as /swagger/v1/swagger.json. This file can then be read by Swagger UI to render an interactive webpage that allows users to test requests right from their browser. The entire process is automated and ensures that the documentation stays up-to-date with the code, unlike manually maintained documentation which can become outdated.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
