Convert OpenAPI/Swagger JSON to YAML [Complete Guide]

Why Use YAML for OpenAPI?

Many developers prefer YAML over JSON for OpenAPI specifications. Here's why the Swagger JSON vs YAML debate often favors YAML:

• Comments: YAML supports comments (#), perfect for documenting API design decisions
• Readability: Cleaner syntax without brackets and braces
• Manual editing: Easier to write and modify by hand
• Industry standard: Most OpenAPI examples and tutorials use YAML

Method 1: Online Converter (Recommended)

The fastest way to convert Swagger JSON to YAML is using our free online converter:

1. Open the converter: Navigate to our JSON to YAML converter
2. Paste your OpenAPI JSON: Copy your entire OpenAPI/Swagger specification
3. Click Convert: The tool instantly converts to YAML
4. Download or copy: Save the YAML file or copy to clipboard

Example: OpenAPI 3.0 Conversion

Input (JSON):

{
  "openapi": "3.0.0",
  "info": {
    "title": "Pet Store API",
    "version": "1.0.0",
    "description": "A sample API for pet store"
  },
  "paths": {
    "/pets": {
      "get": {
        "summary": "List all pets",
        "responses": {
          "200": {
            "description": "A list of pets"
          }
        }
      }
    }
  }
}

Output (YAML):

openapi: 3.0.0
info:
  title: Pet Store API
  version: 1.0.0
  description: A sample API for pet store
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        '200':
          description: A list of pets

Method 2: Swagger Editor

The official Swagger Editor can convert between JSON and YAML while also validating your OpenAPI specification:

1. Go to editor.swagger.io
2. Click File → Import File or paste your JSON
3. The editor automatically displays as YAML
4. Click File → Save as YAML to download

Method 3: Command Line

For automation and CI/CD pipelines, use command-line tools to convert OpenAPI JSON to YAML:

Using yq

# Install yq
brew install yq  # macOS
sudo apt-get install yq  # Ubuntu

# Convert OpenAPI JSON to YAML
yq -P openapi.json > openapi.yaml

# With specific indent (2 spaces is OpenAPI standard)
yq -P --indent 2 openapi.json > openapi.yaml

Using Python

# One-liner conversion
python -c "import json,yaml,sys; print(yaml.dump(json.load(open('openapi.json')), default_flow_style=False))" > openapi.yaml

Using Node.js

# Install js-yaml
npm install -g js-yaml

# Convert (using npx)
npx js-yaml openapi.json > openapi.yaml

OpenAPI JSON vs YAML Comparison

When deciding between OpenAPI JSON vs YAML, consider these factors:

Recommendation: Use YAML for manual editing and documentation. Use JSON for programmatic generation and API gateways.

Convert OpenAPI YAML to JSON

Need to convert Swagger YAML to JSON? Here's how to reverse the process:

# Using yq
yq -o json openapi.yaml > openapi.json

# Using Python
python -c "import json,yaml; print(json.dumps(yaml.safe_load(open('openapi.yaml')), indent=2))" > openapi.json

# Online: Use our YAML to JSON converter
# Simply paste YAML and convert to JSON

Best Practices

For OpenAPI YAML Files

• Use 2-space indentation: This is the OpenAPI standard
• Add comments: Document API design decisions with # comments
• Quote strings when needed: Avoid YAML parsing issues
• Validate after conversion: Use Swagger Editor or spectral

For CI/CD Pipelines

# GitHub Actions example: Validate & Convert OpenAPI
- name: Convert OpenAPI JSON to YAML
  run: |
    yq -P api/openapi.json > api/openapi.yaml
    
- name: Validate OpenAPI spec
  run: |
    npx @stoplight/spectral-cli lint api/openapi.yaml