What it is
OpenAPI (formerly Swagger) is a specification format for describing REST APIs, covering endpoints, parameters, and schemas in a machine-readable JSON or YAML document.
When to use it
API designers and backend developers use this when validating a spec before publishing it, converting between JSON and YAML, or diffing two versions to spot breaking changes.
Gotchas & limits
Swagger 2.0 and OpenAPI 3.x differ in structure for things like request bodies and security schemes, so a spec that validates under one version may fail under the other.