JSONKit
API Design

OpenAPI 3.1 Specification (JSON) JSON Example

An OpenAPI 3.1 specification JSON example — info, a path operation with parameters, responses, and a component schema. Copy-ready reference for documenting and validating REST APIs.

{
  "openapi": "3.1.0",
  "info": {
    "title": "Orders API",
    "version": "1.0.0"
  },
  "paths": {
    "/orders/{id}": {
      "get": {
        "summary": "Get an order by id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The order",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "404": {
            "description": "Order not found"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Order": {
        "type": "object",
        "required": [
          "id",
          "total"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "total": {
            "type": "number"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "paid",
              "shipped"
            ]
          }
        }
      }
    }
  }
}

Field Reference

openapirequiredstringSpec version — '3.1.0' aligns OpenAPI with JSON Schema
inforequiredobjectAPI metadata: title and version (required), plus description, contact, license
pathsrequiredobjectMap of URL path → operations (get, post, put, delete, …)
components.schemasoptionalobjectReusable JSON Schemas referenced via $ref to avoid duplication
$refoptionalstringJSON Reference pointer to a reusable component, e.g. #/components/schemas/Order

Variants

POST operation with request bodyA create endpoint with a JSON request body schema.
POST operation with request body
{
  "post": {
    "summary": "Create an order",
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Order"
          }
        }
      }
    },
    "responses": {
      "201": {
        "description": "Created"
      }
    }
  }
}

Common Use Cases

  • →Documenting a REST API so tools can generate docs and client SDKs
  • →Validating requests and responses against a contract
  • →Designing an API contract-first before writing code
openapiswaggerapi specrest apiapi documentationschema

Validate or format this JSON

One click loads this exact example into the tool — no copy-paste needed. Format it, validate it, explore the tree, or generate TypeScript types instantly.

FormatValidateExplore treeGenerate TypeScriptMinify

Frequently Asked Questions

OpenAPI 3.1 is fully compatible with JSON Schema 2020-12, so the schemas in your spec are now standard JSON Schema (with keywords like examples, and proper null handling via type arrays). It also added the webhooks top-level object and made the info.summary field available.

$ref is a JSON Reference pointer that lets you define a schema, parameter, or response once under components and reuse it everywhere via a path like #/components/schemas/Order. It keeps specs DRY and consistent.

Swagger was the original name; since version 3.0 the specification is called OpenAPI, maintained by the OpenAPI Initiative. 'Swagger' now refers to the tooling (Swagger UI, Swagger Editor) built around the OpenAPI spec.

Related JSON Examples

API DesignREST API ResponseGeneric REST API response wrapper with data payload, status, and pagination meta.API DesignError ResponseREST API error JSON with status code, machine-readable error code, and validation details.AI & LLMMCP Message (Model Context Protocol)Model Context Protocol (MCP) JSON-RPC 2.0 message: tools/list and tools/call.