{
  "openapi": "3.0.3",
  "info": {
    "title": "SeedAPI Online",
    "version": "1.1.0",
    "description": "## API Standards Guide\nApplication Programming Interface (API) standards are collections of rules, protocols, and standardized formats allowing different software systems to connect, communicate, and exchange data consistently, securely, and efficiently.\n\n### 1. Popular API Architectures\n- **REST (Representational State Transfer)**: The most prevalent architectural style running on HTTP, utilizing methods like `GET`, `POST`, `PUT`, `DELETE` to manipulate data resources.\n- **SOAP (Simple Object Access Protocol)**: A highly structured XML-based protocol favored by banks and large enterprises demanding rigorous security standards.\n- **GraphQL**: A modern query language enabling clients to request exactly the data they need, minimizing payloads.\n\n### 2. Key Components\n- **Endpoint**: The target URL accessible for API consumption (e.g., `/api/v1/seeds`).\n- **Methods**: Standard actions: `GET` (Fetch), `POST` (Create), `PUT` (Update), `DELETE` (Remove).\n- **Data Format**: Most commonly light-weight and human-readable `JSON`, followed by `XML`.\n- **Authentication**: Security protocols ensuring safety (e.g., `Bearer Token`, `Sanctum`).\n\n### 3. API Documentation Standards\nEnsuring developer understandability without exposing source logic:\n- **Descriptions**: Functional overviews of every capability.\n- **Parameters**: Clarification on mandatory vs optional input variables.\n- **Responses**: Structured data schemas and standard semantic status codes (e.g., `200 OK`, `404 Not Found`, `500 Error`)."
  },
  "servers": [
    {
      "url": "/api",
      "description": "API base"
    }
  ],
  "tags": [
    {
      "name": "Auth",
      "description": "Register and login"
    },
    {
      "name": "Seed",
      "description": "Free seed data generation"
    },
    {
      "name": "System",
      "description": "Health and account info"
    }
  ],
  "paths": {
    "/v1/health": {
      "get": {
        "tags": ["System"],
        "summary": "Health check",
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "service": { "type": "string" },
                    "version": { "type": "string", "example": "v1" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/register": {
      "post": {
        "tags": ["Auth"],
        "summary": "Register a new account",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "email", "password", "password_confirmation"],
                "properties": {
                  "name": { "type": "string", "example": "Demo User" },
                  "email": { "type": "string", "format": "email", "example": "demo@example.com" },
                  "password": { "type": "string", "format": "password", "example": "password123" },
                  "password_confirmation": { "type": "string", "format": "password", "example": "password123" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Account created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": { "type": "string" },
                    "token_type": { "type": "string", "example": "Bearer" },
                    "access_token": { "type": "string" },
                    "user": {
                      "type": "object",
                      "properties": {
                        "id": { "type": "integer" },
                        "name": { "type": "string" },
                        "email": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": { "description": "Validation error" }
        }
      }
    },
    "/v1/login": {
      "post": {
        "tags": ["Auth"],
        "summary": "Login and receive a bearer token",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "password"],
                "properties": {
                  "email": { "type": "string", "format": "email", "example": "demo@example.com" },
                  "password": { "type": "string", "format": "password", "example": "password123" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Login success" },
          "422": { "description": "Validation error" }
        }
      }
    },
    "/v1/me": {
      "get": {
        "tags": ["System"],
        "summary": "Current authenticated user",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "Authenticated user" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/v1/logout": {
      "post": {
        "tags": ["System"],
        "summary": "Revoke the current bearer token",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "Token revoked" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/v1/seeds": {
      "get": {
        "tags": ["Seed"],
        "summary": "Generate seed data",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "users", "products", "articles", "companies",
                "orders", "reviews", "categories", "posts", 
                "comments", "notifications", "transactions", "credit-cards", 
                "currencies", "projects", "tasks", "audit-logs", 
                "multimedia", "sports", "places", "weather"
              ]
            }
          },
          {
            "name": "count",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "example": 10
            }
          }
        ],
        "responses": {
          "200": { 
            "description": "Seed data successfully generated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": { "type": "string", "example": "Seed data generated successfully." },
                    "type": { "type": "string", "example": "products" },
                    "count": { "type": "integer", "example": 1 },
                    "data": {
                      "type": "array",
                      "items": { "type": "object" }
                    }
                  }
                },
                "example": {
                  "message": "Seed data generated successfully.",
                  "type": "products",
                  "count": 1,
                  "data": [
                    {
                      "sku": "SKU-1234-AB",
                      "name": "Premium Product",
                      "price": 99.99,
                      "stock": 142
                    }
                  ]
                }
              }
            }
          },
          "401": { "description": "Unauthorized - Invalid or missing Bearer token." },
          "429": { "description": "Rate limit exceeded - Maximum quota reached." }
        }
      }
    },
    "/v1/seeds/{type}": {
      "get": {
        "tags": ["Seed"],
        "summary": "Generate one item for a specific seed type",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "name": "type",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "users", "products", "articles", "companies",
                "orders", "reviews", "categories", "posts", 
                "comments", "notifications", "transactions", "credit-cards", 
                "currencies", "projects", "tasks", "audit-logs", 
                "multimedia", "sports", "places", "weather"
              ]
            }
          }
        ],
        "responses": {
          "200": { 
            "description": "Specific seed record generated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": { "type": "string", "example": "Seed data generated successfully." },
                    "type": { "type": "string", "example": "weather" },
                    "data": { "type": "object" }
                  }
                },
                "example": {
                  "message": "Seed data generated successfully.",
                  "type": "weather",
                  "data": {
                    "temperature": "28°C",
                    "humidity": "60%",
                    "condition": "sunny"
                  }
                }
              }
            }
          },
          "401": { "description": "Unauthorized - Token invalid." },
          "404": { "description": "Not Found - Unknown seed type requested." },
          "429": { "description": "Quota Exceeded - Rate limit struck." }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Sanctum token"
      }
    }
  }
}