{
  "openapi": "3.1.0",
  "info": {
    "title": "Classic Fake REST API",
    "version": "1.0",
    "description": "A familiar fake REST API — users, posts, comments, todos, products, carts and quotes — with search, sort, select and page/skip paging. Unlike most, writes persist in your sandbox, carry ETags and validate per field."
  },
  "servers": [
    {
      "url": "https://funapi.dev/api/classic/v1"
    }
  ],
  "tags": [
    {
      "name": "users",
      "description": "full CRUD"
    },
    {
      "name": "posts",
      "description": "full CRUD"
    },
    {
      "name": "comments",
      "description": "full CRUD"
    },
    {
      "name": "todos",
      "description": "full CRUD"
    },
    {
      "name": "products",
      "description": "full CRUD"
    },
    {
      "name": "carts",
      "description": "full CRUD"
    },
    {
      "name": "quotes",
      "description": "read-only"
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "tags": [
          "users"
        ],
        "summary": "List users — search, filter, sort, select and paginate",
        "operationId": "cl-users-list",
        "responses": {
          "200": {
            "description": "A page of records with Link and X-Total-Count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "number"
                          },
                          "firstName": {
                            "type": "string"
                          },
                          "lastName": {
                            "type": "string"
                          },
                          "username": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string"
                          },
                          "phone": {
                            "type": "string"
                          },
                          "age": {
                            "type": "number"
                          },
                          "role": {
                            "type": "string"
                          },
                          "company": {
                            "type": "string"
                          },
                          "address": {
                            "type": "object",
                            "properties": {
                              "city": {
                                "type": "string"
                              },
                              "zip": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "number"
                    },
                    "skip": {
                      "type": "number"
                    },
                    "limit": {
                      "type": "number"
                    },
                    "page": {
                      "type": "number"
                    },
                    "totalPages": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "skip past the last record",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number (1-based). Use page or skip, not both.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1–100, default 10 (aliases: pageSize, per_page).",
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 5
          },
          {
            "name": "skip",
            "in": "query",
            "required": false,
            "description": "Offset-style paging: records to skip.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case-insensitive search.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Field to sort by.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "description": "asc (default) or desc; needs sort.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "select",
            "in": "query",
            "required": false,
            "description": "Comma-separated fields to return (id is always included).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "role",
            "in": "query",
            "required": false,
            "description": "Filter by role.",
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "post": {
        "tags": [
          "users"
        ],
        "summary": "Create a user — it persists in your sandbox",
        "operationId": "cl-users-create",
        "responses": {
          "201": {
            "description": "Created, with Location and ETag",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "firstName": {
                      "type": "string"
                    },
                    "lastName": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    },
                    "age": {
                      "type": "number"
                    }
                  }
                }
              }
            },
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri-reference"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed, per field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "firstName": {
                    "type": "string"
                  },
                  "lastName": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "age": {
                    "type": "number"
                  }
                }
              },
              "example": {
                "firstName": "Test",
                "lastName": "User",
                "email": "test.user@example.com",
                "age": 30
              }
            }
          }
        }
      }
    },
    "/users/{id}": {
      "get": {
        "tags": [
          "users"
        ],
        "summary": "Get one user (ETag; If-None-Match → 304)",
        "operationId": "cl-users-get",
        "responses": {
          "200": {
            "description": "User",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "firstName": {
                      "type": "string"
                    },
                    "lastName": {
                      "type": "string"
                    },
                    "username": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    },
                    "phone": {
                      "type": "string"
                    },
                    "age": {
                      "type": "number"
                    },
                    "role": {
                      "type": "string"
                    },
                    "company": {
                      "type": "string"
                    },
                    "address": {
                      "type": "object",
                      "properties": {
                        "city": {
                          "type": "string"
                        },
                        "zip": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "304": {
            "description": "Not modified"
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          }
        ]
      },
      "put": {
        "tags": [
          "users"
        ],
        "summary": "Replace a user (If-Match supported)",
        "operationId": "cl-users-replace",
        "responses": {
          "200": {
            "description": "Replaced",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "firstName": {
                      "type": "string"
                    },
                    "lastName": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    },
                    "age": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "firstName": {
                    "type": "string"
                  },
                  "lastName": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "age": {
                    "type": "number"
                  }
                }
              },
              "example": {
                "firstName": "Test",
                "lastName": "User",
                "email": "test.user@example.com",
                "age": 30
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "users"
        ],
        "summary": "Update fields of a user (If-Match supported)",
        "operationId": "cl-users-patch",
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "firstName": {
                      "type": "string"
                    },
                    "lastName": {
                      "type": "string"
                    },
                    "username": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    },
                    "phone": {
                      "type": "string"
                    },
                    "age": {
                      "type": "number"
                    },
                    "role": {
                      "type": "string"
                    },
                    "company": {
                      "type": "string"
                    },
                    "address": {
                      "type": "object",
                      "properties": {
                        "city": {
                          "type": "string"
                        },
                        "zip": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "age": {
                    "type": "number"
                  }
                }
              },
              "example": {
                "age": 30
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "users"
        ],
        "summary": "Delete a user — a later GET really returns 404",
        "operationId": "cl-users-delete",
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/posts": {
      "get": {
        "tags": [
          "posts"
        ],
        "summary": "List posts — search, filter, sort, select and paginate",
        "operationId": "cl-posts-list",
        "responses": {
          "200": {
            "description": "A page of records with Link and X-Total-Count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "number"
                          },
                          "userId": {
                            "type": "number"
                          },
                          "title": {
                            "type": "string"
                          },
                          "body": {
                            "type": "string"
                          },
                          "tags": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "views": {
                            "type": "number"
                          },
                          "likes": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "number"
                    },
                    "skip": {
                      "type": "number"
                    },
                    "limit": {
                      "type": "number"
                    },
                    "page": {
                      "type": "number"
                    },
                    "totalPages": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "skip past the last record",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number (1-based). Use page or skip, not both.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1–100, default 10 (aliases: pageSize, per_page).",
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 5
          },
          {
            "name": "skip",
            "in": "query",
            "required": false,
            "description": "Offset-style paging: records to skip.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case-insensitive search.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Field to sort by.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "description": "asc (default) or desc; needs sort.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "select",
            "in": "query",
            "required": false,
            "description": "Comma-separated fields to return (id is always included).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "userId",
            "in": "query",
            "required": false,
            "description": "Filter by userId.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ]
      },
      "post": {
        "tags": [
          "posts"
        ],
        "summary": "Create a post — it persists in your sandbox",
        "operationId": "cl-posts-create",
        "responses": {
          "201": {
            "description": "Created, with Location and ETag",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "userId": {
                      "type": "number"
                    },
                    "title": {
                      "type": "string"
                    },
                    "body": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri-reference"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed, per field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "number"
                  },
                  "title": {
                    "type": "string"
                  },
                  "body": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "userId": 1,
                "title": "My first post",
                "body": "Written from an API test."
              }
            }
          }
        }
      }
    },
    "/posts/{id}": {
      "get": {
        "tags": [
          "posts"
        ],
        "summary": "Get one post (ETag; If-None-Match → 304)",
        "operationId": "cl-posts-get",
        "responses": {
          "200": {
            "description": "Post",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "userId": {
                      "type": "number"
                    },
                    "title": {
                      "type": "string"
                    },
                    "body": {
                      "type": "string"
                    },
                    "tags": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "views": {
                      "type": "number"
                    },
                    "likes": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "304": {
            "description": "Not modified"
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          }
        ]
      },
      "put": {
        "tags": [
          "posts"
        ],
        "summary": "Replace a post (If-Match supported)",
        "operationId": "cl-posts-replace",
        "responses": {
          "200": {
            "description": "Replaced",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "userId": {
                      "type": "number"
                    },
                    "title": {
                      "type": "string"
                    },
                    "body": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "number"
                  },
                  "title": {
                    "type": "string"
                  },
                  "body": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "userId": 1,
                "title": "My first post",
                "body": "Written from an API test."
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "posts"
        ],
        "summary": "Update fields of a post (If-Match supported)",
        "operationId": "cl-posts-patch",
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "userId": {
                      "type": "number"
                    },
                    "title": {
                      "type": "string"
                    },
                    "body": {
                      "type": "string"
                    },
                    "tags": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "views": {
                      "type": "number"
                    },
                    "likes": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "body": "Written from an API test."
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "posts"
        ],
        "summary": "Delete a post — a later GET really returns 404",
        "operationId": "cl-posts-delete",
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/comments": {
      "get": {
        "tags": [
          "comments"
        ],
        "summary": "List comments — search, filter, sort, select and paginate",
        "operationId": "cl-comments-list",
        "responses": {
          "200": {
            "description": "A page of records with Link and X-Total-Count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "number"
                          },
                          "postId": {
                            "type": "number"
                          },
                          "userId": {
                            "type": "number"
                          },
                          "body": {
                            "type": "string"
                          },
                          "likes": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "number"
                    },
                    "skip": {
                      "type": "number"
                    },
                    "limit": {
                      "type": "number"
                    },
                    "page": {
                      "type": "number"
                    },
                    "totalPages": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "skip past the last record",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number (1-based). Use page or skip, not both.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1–100, default 10 (aliases: pageSize, per_page).",
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 5
          },
          {
            "name": "skip",
            "in": "query",
            "required": false,
            "description": "Offset-style paging: records to skip.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case-insensitive search.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Field to sort by.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "description": "asc (default) or desc; needs sort.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "select",
            "in": "query",
            "required": false,
            "description": "Comma-separated fields to return (id is always included).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "postId",
            "in": "query",
            "required": false,
            "description": "Filter by postId.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "userId",
            "in": "query",
            "required": false,
            "description": "Filter by userId.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ]
      },
      "post": {
        "tags": [
          "comments"
        ],
        "summary": "Create a comment — it persists in your sandbox",
        "operationId": "cl-comments-create",
        "responses": {
          "201": {
            "description": "Created, with Location and ETag",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "postId": {
                      "type": "number"
                    },
                    "userId": {
                      "type": "number"
                    },
                    "body": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri-reference"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed, per field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "postId": {
                    "type": "number"
                  },
                  "userId": {
                    "type": "number"
                  },
                  "body": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "postId": 1,
                "userId": 2,
                "body": "Great write-up."
              }
            }
          }
        }
      }
    },
    "/comments/{id}": {
      "get": {
        "tags": [
          "comments"
        ],
        "summary": "Get one comment (ETag; If-None-Match → 304)",
        "operationId": "cl-comments-get",
        "responses": {
          "200": {
            "description": "Comment",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "postId": {
                      "type": "number"
                    },
                    "userId": {
                      "type": "number"
                    },
                    "body": {
                      "type": "string"
                    },
                    "likes": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "304": {
            "description": "Not modified"
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          }
        ]
      },
      "put": {
        "tags": [
          "comments"
        ],
        "summary": "Replace a comment (If-Match supported)",
        "operationId": "cl-comments-replace",
        "responses": {
          "200": {
            "description": "Replaced",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "postId": {
                      "type": "number"
                    },
                    "userId": {
                      "type": "number"
                    },
                    "body": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "postId": {
                    "type": "number"
                  },
                  "userId": {
                    "type": "number"
                  },
                  "body": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "postId": 1,
                "userId": 2,
                "body": "Great write-up."
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "comments"
        ],
        "summary": "Update fields of a comment (If-Match supported)",
        "operationId": "cl-comments-patch",
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "postId": {
                      "type": "number"
                    },
                    "userId": {
                      "type": "number"
                    },
                    "body": {
                      "type": "string"
                    },
                    "likes": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "body": "Great write-up."
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "comments"
        ],
        "summary": "Delete a comment — a later GET really returns 404",
        "operationId": "cl-comments-delete",
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/todos": {
      "get": {
        "tags": [
          "todos"
        ],
        "summary": "List todos — search, filter, sort, select and paginate",
        "operationId": "cl-todos-list",
        "responses": {
          "200": {
            "description": "A page of records with Link and X-Total-Count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "number"
                          },
                          "userId": {
                            "type": "number"
                          },
                          "title": {
                            "type": "string"
                          },
                          "completed": {
                            "type": "boolean"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "number"
                    },
                    "skip": {
                      "type": "number"
                    },
                    "limit": {
                      "type": "number"
                    },
                    "page": {
                      "type": "number"
                    },
                    "totalPages": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "skip past the last record",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number (1-based). Use page or skip, not both.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1–100, default 10 (aliases: pageSize, per_page).",
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 5
          },
          {
            "name": "skip",
            "in": "query",
            "required": false,
            "description": "Offset-style paging: records to skip.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case-insensitive search.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Field to sort by.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "description": "asc (default) or desc; needs sort.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "select",
            "in": "query",
            "required": false,
            "description": "Comma-separated fields to return (id is always included).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "userId",
            "in": "query",
            "required": false,
            "description": "Filter by userId.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "completed",
            "in": "query",
            "required": false,
            "description": "Filter by completed.",
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "post": {
        "tags": [
          "todos"
        ],
        "summary": "Create a todo — it persists in your sandbox",
        "operationId": "cl-todos-create",
        "responses": {
          "201": {
            "description": "Created, with Location and ETag",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "userId": {
                      "type": "number"
                    },
                    "title": {
                      "type": "string"
                    },
                    "completed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            },
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri-reference"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed, per field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "number"
                  },
                  "title": {
                    "type": "string"
                  },
                  "completed": {
                    "type": "boolean"
                  }
                }
              },
              "example": {
                "userId": 1,
                "title": "Write a test for 412",
                "completed": false
              }
            }
          }
        }
      }
    },
    "/todos/{id}": {
      "get": {
        "tags": [
          "todos"
        ],
        "summary": "Get one todo (ETag; If-None-Match → 304)",
        "operationId": "cl-todos-get",
        "responses": {
          "200": {
            "description": "Todo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "userId": {
                      "type": "number"
                    },
                    "title": {
                      "type": "string"
                    },
                    "completed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "304": {
            "description": "Not modified"
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          }
        ]
      },
      "put": {
        "tags": [
          "todos"
        ],
        "summary": "Replace a todo (If-Match supported)",
        "operationId": "cl-todos-replace",
        "responses": {
          "200": {
            "description": "Replaced",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "userId": {
                      "type": "number"
                    },
                    "title": {
                      "type": "string"
                    },
                    "completed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "number"
                  },
                  "title": {
                    "type": "string"
                  },
                  "completed": {
                    "type": "boolean"
                  }
                }
              },
              "example": {
                "userId": 1,
                "title": "Write a test for 412",
                "completed": false
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "todos"
        ],
        "summary": "Update fields of a todo (If-Match supported)",
        "operationId": "cl-todos-patch",
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "userId": {
                      "type": "number"
                    },
                    "title": {
                      "type": "string"
                    },
                    "completed": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "completed": {
                    "type": "boolean"
                  }
                }
              },
              "example": {
                "completed": false
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "todos"
        ],
        "summary": "Delete a todo — a later GET really returns 404",
        "operationId": "cl-todos-delete",
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/products": {
      "get": {
        "tags": [
          "products"
        ],
        "summary": "List products — search, filter, sort, select and paginate",
        "operationId": "cl-products-list",
        "responses": {
          "200": {
            "description": "A page of records with Link and X-Total-Count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "number"
                          },
                          "title": {
                            "type": "string"
                          },
                          "category": {
                            "type": "string"
                          },
                          "price": {
                            "type": "number"
                          },
                          "stock": {
                            "type": "number"
                          },
                          "rating": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "number"
                    },
                    "skip": {
                      "type": "number"
                    },
                    "limit": {
                      "type": "number"
                    },
                    "page": {
                      "type": "number"
                    },
                    "totalPages": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "skip past the last record",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number (1-based). Use page or skip, not both.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1–100, default 10 (aliases: pageSize, per_page).",
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 5
          },
          {
            "name": "skip",
            "in": "query",
            "required": false,
            "description": "Offset-style paging: records to skip.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case-insensitive search.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Field to sort by.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "description": "asc (default) or desc; needs sort.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "select",
            "in": "query",
            "required": false,
            "description": "Comma-separated fields to return (id is always included).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter by category.",
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "post": {
        "tags": [
          "products"
        ],
        "summary": "Create a product — it persists in your sandbox",
        "operationId": "cl-products-create",
        "responses": {
          "201": {
            "description": "Created, with Location and ETag",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "title": {
                      "type": "string"
                    },
                    "category": {
                      "type": "string"
                    },
                    "price": {
                      "type": "number"
                    },
                    "stock": {
                      "type": "number"
                    }
                  }
                }
              }
            },
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri-reference"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed, per field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "category": {
                    "type": "string"
                  },
                  "price": {
                    "type": "number"
                  },
                  "stock": {
                    "type": "number"
                  }
                }
              },
              "example": {
                "title": "Test widget",
                "category": "office",
                "price": 9.99,
                "stock": 10
              }
            }
          }
        }
      }
    },
    "/products/{id}": {
      "get": {
        "tags": [
          "products"
        ],
        "summary": "Get one product (ETag; If-None-Match → 304)",
        "operationId": "cl-products-get",
        "responses": {
          "200": {
            "description": "Product",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "title": {
                      "type": "string"
                    },
                    "category": {
                      "type": "string"
                    },
                    "price": {
                      "type": "number"
                    },
                    "stock": {
                      "type": "number"
                    },
                    "rating": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "304": {
            "description": "Not modified"
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          }
        ]
      },
      "put": {
        "tags": [
          "products"
        ],
        "summary": "Replace a product (If-Match supported)",
        "operationId": "cl-products-replace",
        "responses": {
          "200": {
            "description": "Replaced",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "title": {
                      "type": "string"
                    },
                    "category": {
                      "type": "string"
                    },
                    "price": {
                      "type": "number"
                    },
                    "stock": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "category": {
                    "type": "string"
                  },
                  "price": {
                    "type": "number"
                  },
                  "stock": {
                    "type": "number"
                  }
                }
              },
              "example": {
                "title": "Test widget",
                "category": "office",
                "price": 9.99,
                "stock": 10
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "products"
        ],
        "summary": "Update fields of a product (If-Match supported)",
        "operationId": "cl-products-patch",
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "title": {
                      "type": "string"
                    },
                    "category": {
                      "type": "string"
                    },
                    "price": {
                      "type": "number"
                    },
                    "stock": {
                      "type": "number"
                    },
                    "rating": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "stock": {
                    "type": "number"
                  }
                }
              },
              "example": {
                "stock": 10
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "products"
        ],
        "summary": "Delete a product — a later GET really returns 404",
        "operationId": "cl-products-delete",
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/carts": {
      "get": {
        "tags": [
          "carts"
        ],
        "summary": "List carts — search, filter, sort, select and paginate",
        "operationId": "cl-carts-list",
        "responses": {
          "200": {
            "description": "A page of records with Link and X-Total-Count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "number"
                          },
                          "userId": {
                            "type": "number"
                          },
                          "items": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "productId": {
                                  "type": "number"
                                },
                                "title": {
                                  "type": "string"
                                },
                                "price": {
                                  "type": "number"
                                },
                                "quantity": {
                                  "type": "number"
                                },
                                "lineTotal": {
                                  "type": "number"
                                }
                              }
                            }
                          },
                          "totalQuantity": {
                            "type": "number"
                          },
                          "total": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "number"
                    },
                    "skip": {
                      "type": "number"
                    },
                    "limit": {
                      "type": "number"
                    },
                    "page": {
                      "type": "number"
                    },
                    "totalPages": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "skip past the last record",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number (1-based). Use page or skip, not both.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1–100, default 10 (aliases: pageSize, per_page).",
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 5
          },
          {
            "name": "skip",
            "in": "query",
            "required": false,
            "description": "Offset-style paging: records to skip.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case-insensitive search.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Field to sort by.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "description": "asc (default) or desc; needs sort.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "select",
            "in": "query",
            "required": false,
            "description": "Comma-separated fields to return (id is always included).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "userId",
            "in": "query",
            "required": false,
            "description": "Filter by userId.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ]
      },
      "post": {
        "tags": [
          "carts"
        ],
        "summary": "Create a cart — it persists in your sandbox",
        "operationId": "cl-carts-create",
        "responses": {
          "201": {
            "description": "Created, with Location and ETag",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "userId": {
                      "type": "number"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "productId": {
                            "type": "number"
                          },
                          "title": {
                            "type": "string"
                          },
                          "price": {
                            "type": "number"
                          },
                          "quantity": {
                            "type": "number"
                          },
                          "lineTotal": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "totalQuantity": {
                      "type": "number"
                    },
                    "total": {
                      "type": "number"
                    }
                  }
                }
              }
            },
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri-reference"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed, per field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "number"
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "productId": {
                          "type": "number"
                        },
                        "quantity": {
                          "type": "number"
                        }
                      }
                    }
                  }
                }
              },
              "example": {
                "userId": 1,
                "items": [
                  {
                    "productId": 3,
                    "quantity": 2
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/carts/{id}": {
      "get": {
        "tags": [
          "carts"
        ],
        "summary": "Get one cart (ETag; If-None-Match → 304)",
        "operationId": "cl-carts-get",
        "responses": {
          "200": {
            "description": "Cart",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "userId": {
                      "type": "number"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "productId": {
                            "type": "number"
                          },
                          "title": {
                            "type": "string"
                          },
                          "price": {
                            "type": "number"
                          },
                          "quantity": {
                            "type": "number"
                          },
                          "lineTotal": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "totalQuantity": {
                      "type": "number"
                    },
                    "total": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "304": {
            "description": "Not modified"
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          }
        ]
      },
      "put": {
        "tags": [
          "carts"
        ],
        "summary": "Replace a cart (If-Match supported)",
        "operationId": "cl-carts-replace",
        "responses": {
          "200": {
            "description": "Replaced",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "userId": {
                      "type": "number"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "productId": {
                            "type": "number"
                          },
                          "title": {
                            "type": "string"
                          },
                          "price": {
                            "type": "number"
                          },
                          "quantity": {
                            "type": "number"
                          },
                          "lineTotal": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "totalQuantity": {
                      "type": "number"
                    },
                    "total": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "type": "number"
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "productId": {
                          "type": "number"
                        },
                        "quantity": {
                          "type": "number"
                        }
                      }
                    }
                  }
                }
              },
              "example": {
                "userId": 1,
                "items": [
                  {
                    "productId": 3,
                    "quantity": 2
                  }
                ]
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "carts"
        ],
        "summary": "Update fields of a cart (If-Match supported)",
        "operationId": "cl-carts-patch",
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "userId": {
                      "type": "number"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "productId": {
                            "type": "number"
                          },
                          "title": {
                            "type": "string"
                          },
                          "price": {
                            "type": "number"
                          },
                          "quantity": {
                            "type": "number"
                          },
                          "lineTotal": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "totalQuantity": {
                      "type": "number"
                    },
                    "total": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "productId": {
                          "type": "number"
                        },
                        "quantity": {
                          "type": "number"
                        }
                      }
                    }
                  }
                }
              },
              "example": {
                "items": [
                  {
                    "productId": 3,
                    "quantity": 2
                  }
                ]
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "carts"
        ],
        "summary": "Delete a cart — a later GET really returns 404",
        "operationId": "cl-carts-delete",
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "412": {
            "description": "Stale If-Match",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "If-Match",
            "in": "header",
            "required": false,
            "description": "ETag from a previous GET; a stale one is refused with 412.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/users/{id}/posts": {
      "get": {
        "tags": [
          "users"
        ],
        "summary": "Posts by one user (same paging as /posts)",
        "operationId": "cl-user-posts",
        "responses": {
          "200": {
            "description": "Posts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "number"
                          },
                          "userId": {
                            "type": "number"
                          },
                          "title": {
                            "type": "string"
                          },
                          "body": {
                            "type": "string"
                          },
                          "tags": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "views": {
                            "type": "number"
                          },
                          "likes": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "number"
                    },
                    "skip": {
                      "type": "number"
                    },
                    "limit": {
                      "type": "number"
                    },
                    "page": {
                      "type": "number"
                    },
                    "totalPages": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number (1-based). Use page or skip, not both.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1–100, default 10 (aliases: pageSize, per_page).",
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 5
          },
          {
            "name": "skip",
            "in": "query",
            "required": false,
            "description": "Offset-style paging: records to skip.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ]
      }
    },
    "/users/{id}/todos": {
      "get": {
        "tags": [
          "users"
        ],
        "summary": "Todos of one user",
        "operationId": "cl-user-todos",
        "responses": {
          "200": {
            "description": "Todos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "number"
                          },
                          "userId": {
                            "type": "number"
                          },
                          "title": {
                            "type": "string"
                          },
                          "completed": {
                            "type": "boolean"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "number"
                    },
                    "skip": {
                      "type": "number"
                    },
                    "limit": {
                      "type": "number"
                    },
                    "page": {
                      "type": "number"
                    },
                    "totalPages": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "User not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "completed",
            "in": "query",
            "required": false,
            "description": "true or false",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/posts/{id}/comments": {
      "get": {
        "tags": [
          "posts"
        ],
        "summary": "Comments on one post",
        "operationId": "cl-post-comments",
        "responses": {
          "200": {
            "description": "Comments",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "number"
                          },
                          "postId": {
                            "type": "number"
                          },
                          "userId": {
                            "type": "number"
                          },
                          "body": {
                            "type": "string"
                          },
                          "likes": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "number"
                    },
                    "skip": {
                      "type": "number"
                    },
                    "limit": {
                      "type": "number"
                    },
                    "page": {
                      "type": "number"
                    },
                    "totalPages": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Post not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          }
        ]
      }
    },
    "/products/categories": {
      "get": {
        "tags": [
          "products"
        ],
        "summary": "Product categories with counts",
        "operationId": "cl-categories",
        "responses": {
          "200": {
            "description": "Categories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "products": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/quotes": {
      "get": {
        "tags": [
          "quotes"
        ],
        "summary": "List quotes (read-only)",
        "operationId": "cl-quotes-list",
        "responses": {
          "200": {
            "description": "Quotes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "number"
                          },
                          "quote": {
                            "type": "string"
                          },
                          "author": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "number"
                    },
                    "skip": {
                      "type": "number"
                    },
                    "limit": {
                      "type": "number"
                    },
                    "page": {
                      "type": "number"
                    },
                    "totalPages": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number (1-based). Use page or skip, not both.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1–100, default 10 (aliases: pageSize, per_page).",
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 5
          },
          {
            "name": "skip",
            "in": "query",
            "required": false,
            "description": "Offset-style paging: records to skip.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case-insensitive search.",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/quotes/random": {
      "get": {
        "tags": [
          "quotes"
        ],
        "summary": "A random quote",
        "operationId": "cl-quote-random",
        "responses": {
          "200": {
            "description": "Quote",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "quote": {
                      "type": "string"
                    },
                    "author": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/quotes/{id}": {
      "get": {
        "tags": [
          "quotes"
        ],
        "summary": "One quote",
        "operationId": "cl-quote-get",
        "responses": {
          "200": {
            "description": "Quote",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "number"
                    },
                    "quote": {
                      "type": "string"
                    },
                    "author": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Global rate limit exceeded (300 requests a minute per IP) — wait for Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Use qa-admin-token / qa-viewer-token, or a JWT from POST /auth/v1/login."
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Cargo demo key: cargo-key-123."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "requestId": {
            "type": "string"
          }
        },
        "additionalProperties": true
      }
    }
  }
}
