{
  "openapi": "3.1.0",
  "info": {
    "title": "SampleAPI",
    "version": "1.0.0",
    "description": "Public sample REST API and HTTP echo service for testing.",
    "contact": { "name": "SampleAPI", "url": "https://sampleapi.top/contact/", "email": "modularwebsystems@gmail.com" },
    "license": { "name": "Free for testing and learning" }
  },
  "servers": [
    { "url": "https://sampleapi.top/api", "description": "Production" }
  ],
  "tags": [
    { "name": "Resources" },
    { "name": "Echo" },
    { "name": "Status & Delay" },
    { "name": "Auth" },
    { "name": "Utilities" }
  ],
  "paths": {
    "/": {
      "get": {
        "tags": ["Utilities"],
        "summary": "API index",
        "responses": { "200": { "description": "API index document", "content": { "application/json": {} } } }
      }
    },
    "/posts": {
      "get": {
        "tags": ["Resources"], "summary": "List posts",
        "parameters": [
          { "$ref": "#/components/parameters/Page" },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Sort" },
          { "$ref": "#/components/parameters/Order" },
          { "$ref": "#/components/parameters/Q" },
          { "name": "userId", "in": "query", "schema": { "type": "integer" } }
        ],
        "responses": { "200": { "description": "Array of posts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } } } } } }
      },
      "post": {
        "tags": ["Resources"], "summary": "Create post (simulated)",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostInput" } } } },
        "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } } }
      }
    },
    "/posts/{id}": {
      "parameters": [{ "$ref": "#/components/parameters/Id" }],
      "get":    { "tags": ["Resources"], "summary": "Get a post",     "responses": { "200": { "description": "OK" }, "404": { "$ref": "#/components/responses/NotFound" } } },
      "put":    { "tags": ["Resources"], "summary": "Replace a post", "requestBody": { "content": { "application/json": {} } }, "responses": { "200": { "description": "OK" }, "404": { "$ref": "#/components/responses/NotFound" } } },
      "patch":  { "tags": ["Resources"], "summary": "Update a post",  "requestBody": { "content": { "application/json": {} } }, "responses": { "200": { "description": "OK" }, "404": { "$ref": "#/components/responses/NotFound" } } },
      "delete": { "tags": ["Resources"], "summary": "Delete a post",  "responses": { "200": { "description": "OK" }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/posts/{id}/comments": {
      "parameters": [{ "$ref": "#/components/parameters/Id" }],
      "get": { "tags": ["Resources"], "summary": "Comments for a post", "responses": { "200": { "description": "Array of comments" } } }
    },
    "/comments": {
      "get":  { "tags": ["Resources"], "summary": "List comments", "responses": { "200": { "description": "Array of comments" } } },
      "post": { "tags": ["Resources"], "summary": "Create comment (simulated)", "requestBody": { "content": { "application/json": {} } }, "responses": { "201": { "description": "Created" } } }
    },
    "/comments/{id}": {
      "parameters": [{ "$ref": "#/components/parameters/Id" }],
      "get": { "tags": ["Resources"], "summary": "Get a comment", "responses": { "200": { "description": "OK" }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/users": {
      "get":  { "tags": ["Resources"], "summary": "List users", "responses": { "200": { "description": "Array of users" } } },
      "post": { "tags": ["Resources"], "summary": "Create user (simulated)", "requestBody": { "content": { "application/json": {} } }, "responses": { "201": { "description": "Created" } } }
    },
    "/users/{id}":         { "parameters": [{ "$ref": "#/components/parameters/Id" }], "get": { "tags": ["Resources"], "summary": "Get a user", "responses": { "200": { "description": "OK" }, "404": { "$ref": "#/components/responses/NotFound" } } } },
    "/users/{id}/posts":   { "parameters": [{ "$ref": "#/components/parameters/Id" }], "get": { "tags": ["Resources"], "summary": "Posts by user", "responses": { "200": { "description": "OK" } } } },
    "/users/{id}/todos":   { "parameters": [{ "$ref": "#/components/parameters/Id" }], "get": { "tags": ["Resources"], "summary": "Todos by user", "responses": { "200": { "description": "OK" } } } },
    "/todos":              { "get":  { "tags": ["Resources"], "summary": "List todos", "responses": { "200": { "description": "Array of todos" } } }, "post": { "tags": ["Resources"], "summary": "Create todo (simulated)", "requestBody": { "content": { "application/json": {} } }, "responses": { "201": { "description": "Created" } } } },
    "/todos/{id}":         { "parameters": [{ "$ref": "#/components/parameters/Id" }], "get": { "tags": ["Resources"], "summary": "Get a todo", "responses": { "200": { "description": "OK" }, "404": { "$ref": "#/components/responses/NotFound" } } } },

    "/get":      { "get":    { "tags": ["Echo"], "summary": "Echo GET",    "responses": { "200": { "$ref": "#/components/responses/Echo" } } } },
    "/post":     { "post":   { "tags": ["Echo"], "summary": "Echo POST",   "requestBody": { "content": { "application/json": {}, "application/x-www-form-urlencoded": {} } }, "responses": { "200": { "$ref": "#/components/responses/Echo" } } } },
    "/put":      { "put":    { "tags": ["Echo"], "summary": "Echo PUT",    "requestBody": { "content": { "application/json": {} } }, "responses": { "200": { "$ref": "#/components/responses/Echo" } } } },
    "/patch":    { "patch":  { "tags": ["Echo"], "summary": "Echo PATCH",  "requestBody": { "content": { "application/json": {} } }, "responses": { "200": { "$ref": "#/components/responses/Echo" } } } },
    "/delete":   { "delete": { "tags": ["Echo"], "summary": "Echo DELETE", "responses": { "200": { "$ref": "#/components/responses/Echo" } } } },
    "/headers":  { "get":    { "tags": ["Echo"], "summary": "Return request headers", "responses": { "200": { "description": "Headers object" } } } },
    "/ip":       { "get":    { "tags": ["Echo"], "summary": "Return client IP", "responses": { "200": { "description": "IP object" } } } },
    "/user-agent": { "get":  { "tags": ["Echo"], "summary": "Return User-Agent", "responses": { "200": { "description": "UA object" } } } },
    "/anything": { "get": { "tags": ["Echo"], "summary": "Echo any verb", "responses": { "200": { "$ref": "#/components/responses/Echo" } } }, "post": { "tags": ["Echo"], "summary": "Echo any verb", "responses": { "200": { "$ref": "#/components/responses/Echo" } } }, "put": { "tags": ["Echo"], "summary": "Echo any verb", "responses": { "200": { "$ref": "#/components/responses/Echo" } } }, "patch": { "tags": ["Echo"], "summary": "Echo any verb", "responses": { "200": { "$ref": "#/components/responses/Echo" } } }, "delete": { "tags": ["Echo"], "summary": "Echo any verb", "responses": { "200": { "$ref": "#/components/responses/Echo" } } } },

    "/status/{code}": {
      "parameters": [{ "name": "code", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 100, "maximum": 599 } }],
      "get":    { "tags": ["Status & Delay"], "summary": "Return the given status", "responses": { "default": { "description": "Returns the requested status code" } } },
      "post":   { "tags": ["Status & Delay"], "summary": "Return the given status", "responses": { "default": { "description": "Returns the requested status code" } } },
      "put":    { "tags": ["Status & Delay"], "summary": "Return the given status", "responses": { "default": { "description": "Returns the requested status code" } } },
      "patch":  { "tags": ["Status & Delay"], "summary": "Return the given status", "responses": { "default": { "description": "Returns the requested status code" } } },
      "delete": { "tags": ["Status & Delay"], "summary": "Return the given status", "responses": { "default": { "description": "Returns the requested status code" } } }
    },
    "/delay/{seconds}": {
      "parameters": [{ "name": "seconds", "in": "path", "required": true, "schema": { "type": "number", "minimum": 0, "maximum": 5 } }],
      "get": { "tags": ["Status & Delay"], "summary": "Delay response", "responses": { "200": { "description": "Delayed response" } } }
    },

    "/uuid": { "get": { "tags": ["Utilities"], "summary": "Random UUID v4",  "responses": { "200": { "description": "UUID object" } } } },
    "/time": { "get": { "tags": ["Utilities"], "summary": "Server time",     "responses": { "200": { "description": "Time object" } } } },

    "/hash": {
      "post": {
        "tags": ["Body-aware"], "summary": "Hash the raw request body",
        "requestBody": { "required": true, "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } },
        "responses": {
          "200": { "description": "md5/sha1/sha256/crc32 hex digests of the body" },
          "400": { "description": "Empty body" }
        }
      },
      "put": {
        "tags": ["Body-aware"], "summary": "Hash the raw request body (PUT)",
        "requestBody": { "required": true, "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } },
        "responses": { "200": { "description": "Digests object" }, "400": { "description": "Empty body" } }
      }
    },
    "/json-stats": {
      "post": {
        "tags": ["Body-aware"], "summary": "Inspect a JSON body's shape",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } },
        "responses": {
          "200": { "description": "Depth and counts of keys/arrays/objects/strings/numbers/booleans/nulls" },
          "400": { "description": "Invalid JSON" }
        }
      }
    },
    "/validate/post": {
      "post": {
        "tags": ["Body-aware"], "summary": "Validate a post payload",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostInput" } } } },
        "responses": {
          "200": { "description": "Valid; echoes the normalized payload" },
          "422": { "description": "Per-field validation errors" }
        }
      },
      "put":   { "tags": ["Body-aware"], "summary": "Validate (PUT)",   "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostInput" } } } }, "responses": { "200": { "description": "Valid" }, "422": { "description": "Invalid" } } },
      "patch": { "tags": ["Body-aware"], "summary": "Validate (PATCH)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostInput" } } } }, "responses": { "200": { "description": "Valid" }, "422": { "description": "Invalid" } } }
    },

    "/auth/bearer": {
      "get": {
        "tags": ["Auth"], "summary": "Bearer token test",
        "security": [{ "BearerAuth": [] }],
        "responses": {
          "200": { "description": "Authenticated" },
          "401": { "description": "Missing Authorization header" },
          "403": { "description": "Wrong token" }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Id":    { "name": "id",     "in": "path",  "required": true, "schema": { "type": "string" } },
      "Page":  { "name": "_page",  "in": "query", "schema": { "type": "integer", "minimum": 1 } },
      "Limit": { "name": "_limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } },
      "Sort":  { "name": "_sort",  "in": "query", "schema": { "type": "string" } },
      "Order": { "name": "_order", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"] } },
      "Q":     { "name": "q",      "in": "query", "schema": { "type": "string" } }
    },
    "responses": {
      "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Echo":     { "description": "Echo of the incoming request", "content": { "application/json": {} } }
    },
    "securitySchemes": {
      "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Demo" }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error", "status", "message"],
        "properties": {
          "error":   { "type": "boolean" },
          "status":  { "type": "integer" },
          "message": { "type": "string" }
        }
      },
      "Post": {
        "type": "object",
        "properties": {
          "id":        { "type": "integer" },
          "userId":    { "type": "integer" },
          "title":     { "type": "string" },
          "body":      { "type": "string" },
          "tags":      { "type": "array", "items": { "type": "string" } },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "PostInput": {
        "type": "object",
        "required": ["title", "body"],
        "properties": {
          "userId": { "type": "integer" },
          "title":  { "type": "string" },
          "body":   { "type": "string" },
          "tags":   { "type": "array", "items": { "type": "string" } }
        }
      },
      "Comment": {
        "type": "object",
        "properties": {
          "id":     { "type": "integer" },
          "postId": { "type": "integer" },
          "name":   { "type": "string" },
          "email":  { "type": "string" },
          "body":   { "type": "string" }
        }
      },
      "User": {
        "type": "object",
        "properties": {
          "id":       { "type": "integer" },
          "name":     { "type": "string" },
          "username": { "type": "string" },
          "email":    { "type": "string" },
          "phone":    { "type": "string" },
          "website":  { "type": "string" },
          "company":  { "type": "object" },
          "address":  { "type": "object" }
        }
      },
      "Todo": {
        "type": "object",
        "properties": {
          "id":        { "type": "integer" },
          "userId":    { "type": "integer" },
          "title":     { "type": "string" },
          "completed": { "type": "boolean" },
          "dueDate":   { "type": "string", "format": "date" }
        }
      }
    }
  }
}