How to Get OpenAPI YAML from JSON

Introduction

OpenAPI (formerly Swagger) specifications can be written in either JSON or YAML format. While JSON is machine-friendly, YAML is often preferred for its human-readable syntax. This guide covers various methods to convert OpenAPI JSON files to YAML format.

Using Online Conversion Tools

Using Command Line Tools

# Install yq
# macOS: brew install yq
# Linux: sudo apt install yq
# Windows: choco install yq

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

# Or using eval with input
yq eval -P -o yaml openapi.json > openapi.yaml

# Process JSON with jq and convert to YAML
jq . openapi.json | yq eval -P . - > openapi.yaml

# Install PyYAML
pip install pyyaml

# Python script
import json
import yaml

with open('openapi.json', 'r') as json_file:
    json_data = json.load(json_file)

with open('openapi.yaml', 'w') as yaml_file:
    yaml.dump(json_data, yaml_file, default_flow_style=False, sort_keys=False)

Using Node.js

# Install js-yaml
npm install js-yaml

# Node.js script
const fs = require('fs');
const yaml = require('js-yaml');

const jsonData = JSON.parse(fs.readFileSync('openapi.json', 'utf8'));
const yamlData = yaml.dump(jsonData, {
  indent: 2,
  lineWidth: -1,
  noRefs: true
});

fs.writeFileSync('openapi.yaml', yamlData);

# Install packages
npm install swagger-jsdoc yaml

# Convert OpenAPI JSON to YAML
const fs = require('fs');
const YAML = require('yaml');

const jsonData = JSON.parse(fs.readFileSync('openapi.json', 'utf8'));
const yamlString = YAML.stringify(jsonData);

fs.writeFileSync('openapi.yaml', yamlString);

Using OpenAPI-Specific Tools

# Install swagger-codegen
# Download from: https://github.com/swagger-api/swagger-codegen

# Convert JSON to YAML (via validation)
java -jar swagger-codegen-cli.jar validate -i openapi.json

# Note: swagger-codegen primarily generates code,
# but can validate and work with both formats

# Install openapi-generator
# macOS: brew install openapi-generator
# Or download JAR from GitHub

# Validate and convert (indirectly)
openapi-generator validate -i openapi.json

# Use with YAML output format
openapi-generator generate -i openapi.json -g openapi-yaml -o output/

Complete Conversion Example

Example OpenAPI JSON and its YAML equivalent:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Sample API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "Get users",
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    }
  }
}

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get users
      responses:
        '200':
          description: Success

Best Practices

• •
  Validate after conversion - Ensure the YAML file is valid OpenAPI specification
• •
  Preserve formatting - Use tools that maintain proper YAML indentation
• •
  Check references - Verify that $ref references are preserved correctly
• •
  Test the specification - Validate with OpenAPI validators after conversion

Common Issues and Solutions

# YAML automatically quotes numeric keys
responses:
  '200':  # This is correct
    description: Success

# Verify references are intact
components:
  schemas:
    User:
      $ref: '#/components/schemas/User'  # Should remain valid

Related Articles