{
  "openapi": "3.0.3",
  "info": {
    "title": "SwitchMall Public Product Statistics API",
    "version": "1.0.0",
    "description": "Read-only public SwitchMall product view and reaction counts.",
    "contact": {
      "name": "SwitchMall Developer Resources",
      "url": "https://switchmall.ai/developers"
    }
  },
  "externalDocs": {
    "description": "SwitchMall Public API documentation",
    "url": "https://switchmall.ai/developers/api"
  },
  "servers": [
    { "url": "https://switchmall.ai" }
  ],
  "security": [],
  "tags": [
    {
      "name": "SwitchMall Products",
      "description": "Read-only public information associated with SwitchMall product IDs."
    }
  ],
  "paths": {
    "/api/public/v1/products/{productId}/stats": {
      "get": {
        "operationId": "getSwitchMallProductStats",
        "summary": "Get SwitchMall product statistics",
        "description": "Returns current view, like and dislike counts for a SwitchMall product ID. No authentication is required.",
        "security": [],
        "tags": ["SwitchMall Products"],
        "parameters": [
          {
            "name": "productId",
            "in": "path",
            "required": true,
            "description": "Positive SwitchMall product ID.",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "maximum": 9007199254740991
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "description": "Current SwitchMall product statistics.",
            "headers": {
              "Cache-Control": {
                "description": "Public cache policy for the response.",
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductStats" },
                "example": {
                  "productId": 1,
                  "viewsCount": 0,
                  "likesCount": 0,
                  "dislikesCount": 0
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "405": { "$ref": "#/components/responses/MethodNotAllowed" },
          "429": { "$ref": "#/components/responses/TooManyRequests" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ProductStats": {
        "type": "object",
        "required": ["productId", "viewsCount", "likesCount", "dislikesCount"],
        "properties": {
          "productId": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "maximum": 9007199254740991,
            "description": "SwitchMall product ID supplied in the request path."
          },
          "viewsCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Recorded product view events."
          },
          "likesCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Current positive reactions."
          },
          "dislikesCount": {
            "type": "integer",
            "minimum": 0,
            "description": "Current negative reactions."
          }
        },
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "required": ["error", "code", "message", "resolution"],
        "properties": {
          "error": {
            "type": "string",
            "description": "Backward-compatible human-readable error message."
          },
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code.",
            "enum": ["INVALID_PRODUCT_ID", "METHOD_NOT_ALLOWED", "RATE_LIMIT_EXCEEDED", "INTERNAL_ERROR", "API_ROUTE_NOT_FOUND"]
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation of the failure."
          },
          "resolution": {
            "type": "string",
            "description": "Concrete guidance for correcting or retrying the request."
          }
        },
        "additionalProperties": false
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid SwitchMall product ID.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": {
              "error": "Product ID must be a positive integer",
              "code": "INVALID_PRODUCT_ID",
              "message": "Product ID must be a positive integer",
              "resolution": "Provide a positive integer SwitchMall product ID in the URL path."
            }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "Unsupported HTTP method.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": {
              "error": "Method not allowed",
              "code": "METHOD_NOT_ALLOWED",
              "message": "Method not allowed",
              "resolution": "Call this endpoint with GET or OPTIONS."
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Public rate limit exceeded.",
        "headers": {
          "Retry-After": {
            "description": "Seconds until another request may be attempted.",
            "schema": { "type": "integer", "minimum": 1 }
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": {
              "error": "Rate limit exceeded",
              "code": "RATE_LIMIT_EXCEEDED",
              "message": "Rate limit exceeded",
              "resolution": "Wait for the Retry-After interval before retrying."
            }
          }
        }
      },
      "ServerError": {
        "description": "Unexpected server error.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" },
            "example": {
              "error": "Internal server error",
              "code": "INTERNAL_ERROR",
              "message": "Internal server error",
              "resolution": "Retry later or use the SwitchMall contact page if the problem continues."
            }
          }
        }
      }
    }
  }
}