Swagger YAML and JSON are just two different ways to write down the same OpenAPI Specification (OAS) document, which describes your API.
Let’s see it in action. Here’s a tiny OpenAPI document describing a simple GET request to /users:
YAML Version:
openapi: 3.0.0
info:
title: User API
version: 1.0.0
paths:
/users:
get:
summary: Get a list of users
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
JSON Version:
{
"openapi": "3.0.0",
"info": {
"title": "User API",
"version": "1.0.0"
},
"paths": {
"/users": {
"get": {
"summary": "Get a list of users",
"responses": {
"200": {
"description": "A list of users",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
}
}
Notice how the YAML is more human-readable due to its indentation-based structure, while JSON uses explicit braces and commas. Both represent the exact same API description.
The core problem OAS solves is providing a standardized, machine-readable contract for your API. Before OAS, documenting an API was often a manual, error-prone process. You’d write HTML docs, maybe a PDF, and hope it stayed in sync with the actual code. This led to "API drift," where the documentation didn’t match the reality, causing frustration for developers consuming the API.
OAS, regardless of format, bridges this gap. It’s a formal specification that can be used by various tools:
- Documentation Generation: Tools like Swagger UI or Redoc can take your OAS file and generate interactive API documentation.
- Client/Server SDK Generation: You can generate client libraries (e.g., Python, Java, JavaScript) or server stubs from your OAS file, saving significant development time.
- API Testing: Tools can use the OAS to validate incoming requests and outgoing responses, ensuring they conform to the contract.
- API Gateway Configuration: Some gateways can ingest OAS files to automatically configure routing and security policies.
Internally, an OAS document is a JSON object. Even when you write it in YAML, tools that process it will convert it to its JSON representation first. The OAS specification defines the structure and semantics of this JSON object. It includes sections for:
openapi: The version of the OpenAPI Specification being used (e.g.,3.0.0).info: Metadata about the API, like its title and version.servers: URLs for the API’s available deployments.paths: The core of the document, describing available endpoints, HTTP methods, parameters, request bodies, and responses.components: Reusable elements like schemas, parameters, and security schemes.security: Default security requirements for the API.tags: Metadata to help organize operations.
The fundamental difference between YAML and JSON in this context is syntax and human readability. YAML’s indentation and lack of excessive punctuation make it easier to read and write for humans, especially for larger, more complex API definitions. JSON, with its strict syntax, is often preferred by machines and is the native format for JavaScript and many web APIs.
When choosing between YAML and JSON for your OpenAPI document, consider your team’s preferences and the tools you’re using. Many developers find YAML more approachable for authoring. However, if your tooling ecosystem is heavily JSON-centric, or if you’re dynamically generating OAS documents in code, JSON might be a more natural fit. Most modern OAS tools support both formats, often with automatic conversion capabilities.
The most impactful aspect of this choice is not the format itself, but the discipline of maintaining a single source of truth for your API contract. Whether it’s a .yaml or .json file, keeping it up-to-date with your implementation is paramount.
The next step after defining your API contract is understanding how to define reusable components within your OAS document to avoid repetition.