{
  "openapi": "3.0.3",
  "info": {
    "title": "Super Categories API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "{{baseUrl}}",
      "description": "Base URL"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "SuperCategoryAdmin": {
        "type": "object",
        "properties": {
          "id":        { "type": "string", "example": "664f1a2b3c4d5e6f7a8b9c0d" },
          "name_en":   { "type": "string", "example": "Camping" },
          "name_de":   { "type": "string", "example": "Camping" },
          "order":     { "type": "integer", "example": 1 },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "PaginationMeta": {
        "type": "object",
        "properties": {
          "total":       { "type": "integer", "example": 25 },
          "page":        { "type": "integer", "example": 1 },
          "perPage":     { "type": "integer", "example": 50 },
          "totalPages":  { "type": "integer", "example": 1 }
        }
      },
      "SuccessResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "message": { "type": "string" },
          "data":    { }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "message": { "type": "string" }
        }
      }
    }
  },
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/api/admin/super-categories": {
      "get": {
        "tags": ["Admin / Super Categories"],
        "summary": "List super categories (paginated)",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": { "type": "integer", "default": 1 },
            "example": 1
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 50 },
            "example": 50
          },
          {
            "name": "search",
            "in": "query",
            "schema": { "type": "string" },
            "example": "camp"
          }
        ],
        "responses": {
          "200": {
            "description": "Super categories retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/SuccessResponse" },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "data": {
                              "type": "array",
                              "items": { "$ref": "#/components/schemas/SuperCategoryAdmin" }
                            },
                            "meta": { "$ref": "#/components/schemas/PaginationMeta" }
                          }
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "success": true,
                  "message": "Super categories retrieved successfully",
                  "data": {
                    "data": [
                      {
                        "id": "664f1a2b3c4d5e6f7a8b9c0d",
                        "name_en": "Camping",
                        "name_de": "Camping",
                        "order": 1,
                        "createdAt": "2024-05-01T10:00:00.000Z",
                        "updatedAt": "2024-05-01T10:00:00.000Z"
                      }
                    ],
                    "meta": { "total": 1, "page": 1, "perPage": 50, "totalPages": 1 }
                  }
                }
              }
            }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      },
      "post": {
        "tags": ["Admin / Super Categories"],
        "summary": "Create a super category",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name_en", "name_de"],
                "properties": {
                  "name_en": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Camping" },
                  "name_de": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Camping" },
                  "order":   { "type": "integer", "minimum": 0, "example": 1 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Super category created successfully",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" },
                "example": {
                  "success": true,
                  "message": "Super category created successfully",
                  "data": {
                    "id": "664f1a2b3c4d5e6f7a8b9c0d",
                    "name_en": "Camping",
                    "name_de": "Camping",
                    "order": 1,
                    "createdAt": "2024-05-01T10:00:00.000Z",
                    "updatedAt": "2024-05-01T10:00:00.000Z"
                  }
                }
              }
            }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "422": {
            "description": "Validation error or duplicate name",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": {
                  "success": false,
                  "message": "A super category with this English name already exists"
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/super-categories/reorder": {
      "patch": {
        "tags": ["Admin / Super Categories"],
        "summary": "Bulk reorder super categories",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["orderedIds"],
                "properties": {
                  "orderedIds": {
                    "type": "array",
                    "items": { "type": "string" },
                    "minItems": 1,
                    "example": ["664f1a2b3c4d5e6f7a8b9c0d", "664f1a2b3c4d5e6f7a8b9c0e"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Super categories reordered successfully",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" },
                "example": {
                  "success": true,
                  "message": "Super categories reordered successfully",
                  "data": { "updated": 2 }
                }
              }
            }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "422": {
            "description": "One or more IDs not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": { "success": false, "message": "One or more super category IDs were not found" }
              }
            }
          }
        }
      }
    },
    "/api/admin/super-categories/{id}": {
      "get": {
        "tags": ["Admin / Super Categories"],
        "summary": "Get a single super category",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "664f1a2b3c4d5e6f7a8b9c0d" }
        ],
        "responses": {
          "200": {
            "description": "Super category retrieved successfully",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" },
                "example": {
                  "success": true,
                  "message": "Super category retrieved successfully",
                  "data": {
                    "id": "664f1a2b3c4d5e6f7a8b9c0d",
                    "name_en": "Camping",
                    "name_de": "Camping",
                    "order": 1,
                    "createdAt": "2024-05-01T10:00:00.000Z",
                    "updatedAt": "2024-05-01T10:00:00.000Z"
                  }
                }
              }
            }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "404": {
            "description": "Super category not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": { "success": false, "message": "Super category not found" }
              }
            }
          }
        }
      },
      "patch": {
        "tags": ["Admin / Super Categories"],
        "summary": "Partial update a super category",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "664f1a2b3c4d5e6f7a8b9c0d" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "minProperties": 1,
                "properties": {
                  "name_en": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Camping Updated" },
                  "name_de": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Camping Aktualisiert" },
                  "order":   { "type": "integer", "minimum": 0, "example": 2 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Super category updated successfully",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" },
                "example": {
                  "success": true,
                  "message": "Super category updated successfully",
                  "data": {
                    "id": "664f1a2b3c4d5e6f7a8b9c0d",
                    "name_en": "Camping Updated",
                    "name_de": "Camping Aktualisiert",
                    "order": 2,
                    "createdAt": "2024-05-01T10:00:00.000Z",
                    "updatedAt": "2024-05-02T10:00:00.000Z"
                  }
                }
              }
            }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "422": { "description": "Duplicate name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      },
      "delete": {
        "tags": ["Admin / Super Categories"],
        "summary": "Delete a super category (hard delete)",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "664f1a2b3c4d5e6f7a8b9c0d" }
        ],
        "responses": {
          "200": {
            "description": "Super category deleted successfully",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" },
                "example": {
                  "success": true,
                  "message": "Super category deleted successfully",
                  "data": { "deletedId": "664f1a2b3c4d5e6f7a8b9c0d" }
                }
              }
            }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "409": {
            "description": "Conflict — linked campsite categories exist",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": {
                  "success": false,
                  "message": "This super category is assigned to one or more campsite categories and cannot be deleted"
                }
              }
            }
          }
        }
      }
    },
    "/api/admin/super-categories/{id}/affected-categories": {
      "get": {
        "tags": ["Admin / Super Categories"],
        "summary": "Get count of linked campsite categories",
        "description": "Call this before DELETE to show the mandatory warning dialog to the user.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "664f1a2b3c4d5e6f7a8b9c0d" }
        ],
        "responses": {
          "200": {
            "description": "Affected categories retrieved successfully",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" },
                "example": {
                  "success": true,
                  "message": "Affected categories retrieved successfully",
                  "data": {
                    "superCategoryId": "664f1a2b3c4d5e6f7a8b9c0d",
                    "name_en": "Camping",
                    "name_de": "Camping",
                    "affectedCount": 3
                  }
                }
              }
            }
          },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    }
  }
}