JSON and OpenAPI/Swagger: Documenting Your APIs

OpenAPI (formerly Swagger) is the industry standard for describing REST APIs. It uses JSON Schema as its foundation, adding HTTP-specific metadata like endpoints, parameters, authentication, and response codes. This guide covers OpenAPI specification structure, generating JSON schemas from OpenAPI, extracting sample JSON from API specs, and best practices for API documentation. Use our JSON to OpenAPI tool to generate specs from JSON samples and OpenAPI to JSON to extract sample data.

OpenAPI Structure

{
  "openapi": "3.0.3",
  "info": {
    "title": "Users API",
    "version": "1.0.0",
    "description": "API for managing users"
  },
  "servers": [
    { "url": "https://api.example.com/v1" }
  ],
  "paths": {
    "/users": {
      "get": {
        "summary": "List all users",
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer" } },
          { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserList"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a user",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateUser" }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "email": { "type": "string", "format": "email" }
        },
        "required": ["id", "name", "email"]
      },
      "UserList": {
        "type": "object",
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } },
          "total": { "type": "integer" },
          "page": { "type": "integer" }
        }
      }
    }
  }
}

Generating Sample JSON from OpenAPI

// Our /openapi-to-json tool extracts sample JSON from OpenAPI specs
// Input: OpenAPI schema component
{
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string" },
    "email": { "type": "string", "format": "email" }
  }
}

// Output: Sample JSON
{
  "id": 1,
  "name": "Sample String",
  "email": "user@example.com"
}

Use OpenAPI to JSON to generate sample data from your specs.

Generating OpenAPI from JSON

// Input: JSON data sample
[
  {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com"
  }
]

// Generated OpenAPI schema component
// Use /json-to-openapi to generate
{
  "User": {
    "type": "object",
    "properties": {
      "id": { "type": "integer" },
      "name": { "type": "string" },
      "email": { "type": "string", "format": "email" }
    },
    "required": ["id", "name", "email"]
  }
}

OpenAPI vs JSON Schema

Feature	JSON Schema	OpenAPI
Purpose	General data validation	API specification
HTTP metadata	Not included	Paths, methods, parameters, responses
Authentication	Not applicable	Security schemes (API key, OAuth, JWT)
Servers	Not included	Server URLs and variables
Request bodies	Schema only	Content type, encoding, examples
Response codes	Not applicable	Status codes with descriptions
Version	Draft 2020-12 (latest)	3.0.3 / 3.1.0 (uses JSON Schema)
Tooling	Ajv, json-schema-validator	Swagger UI, Redoc, Postman

OpenAPI 3.1 vs 3.0

OpenAPI 3.1.0 aligns with JSON Schema Draft 2020-12, making it fully compatible. Key differences:

• 3.1.0 uses full JSON Schema (no more OpenAPI-specific modifications)
• nullable is replaced by type: ["string", "null"]
• exclusiveMinimum/exclusiveMaximum use numbers instead of booleans
• example (singular) replaces examples (plural) at the property level
• Webhooks support added

Best Practices for OpenAPI JSON

• Use $ref for reusable schema components to avoid duplication
• Include example values for every property to improve documentation
• Define error response schemas consistently (RFC 7807)
• Use our JSON Validator to validate OpenAPI specs
• Generate OpenAPI from JSON samples with JSON to OpenAPI
• Extract sample JSON with OpenAPI to JSON for testing
• Format OpenAPI specs with JSON Formatter

Next Steps

Generate OpenAPI specs from your JSON with JSON to OpenAPI. Extract sample JSON with OpenAPI to JSON. Validate specs with JSON Validator. Generate JSON Schema with JSON Schema Generator.