API / Swagger Interview questions
What are the supported formats for writing an OpenAPI document?
An OpenAPI document can be written in either YAML or JSON, and both are fully equivalent — tooling that consumes OpenAPI documents (Swagger UI, code generators, validators) accepts either format interchangeably, since JSON is itself a valid subset of YAML's data model.
| YAML | JSON |
| More concise, human-readable, supports comments. | More verbose, no native comment support. |
| Preferred for hand-written, version-controlled specs. | Preferred when a spec is generated or consumed programmatically. |
| Indentation-sensitive; easy to introduce subtle formatting bugs. | Braces/brackets make structure explicit, less indentation-sensitive. |
Most teams that hand-author their OpenAPI documents choose YAML for readability and the ability to leave explanatory comments in the source, converting to JSON only at the point some downstream tool specifically requires it.
Which format supports native comments in the OpenAPI document?
Do tools like Swagger UI require one specific format over the other?
More Related questions...
