{
  "openapi": "3.1.0",
  "info": {
    "title": "Star Wars Name Generator API",
    "version": "1.0.0",
    "summary": "Free public REST API for generating lore-accurate Star Wars character names.",
    "description": "Generate Star Wars character names across 15 species, 4 eras, 6 style presets, and 3 gender modes. No authentication required for basic usage. Powered by a Supabase Edge Function. Trademark: Star Wars\u2122 is property of Lucasfilm Ltd. / The Walt Disney Company. This is an unaffiliated fan project.",
    "termsOfService": "https://starwarsnamegenerator.com/terms-of-service",
    "contact": {
      "name": "Star Wars Name Generator",
      "url": "https://starwarsnamegenerator.com/contact",
      "email": "contact@starwarsnamegenerator.com"
    },
    "license": {
      "name": "Free for personal, non-commercial fan use",
      "url": "https://starwarsnamegenerator.com/terms-of-service"
    },
    "x-logo": {
      "url": "https://starwarsnamegenerator.com/og-image.jpg",
      "altText": "Star Wars Name Generator"
    }
  },
  "externalDocs": {
    "description": "Interactive API playground and code examples",
    "url": "https://starwarsnamegenerator.com/api-docs"
  },
  "servers": [
    {
      "url": "https://vqcjvexnwxnwvaoeofka.supabase.co/functions/v1",
      "description": "Production Supabase Edge Function"
    }
  ],
  "tags": [
    { "name": "Names", "description": "Generate Star Wars character names" },
    { "name": "Meta", "description": "Discover schema and supported options" }
  ],
  "paths": {
    "/generate-names": {
      "get": {
        "tags": ["Meta"],
        "summary": "Get API schema",
        "description": "Returns the API name, version, supported endpoints, and the full list of valid parameter values (species, presets, eras, genders).",
        "operationId": "getApiSchema",
        "responses": {
          "200": {
            "description": "API schema document",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiSchema" }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Names"],
        "summary": "Generate Star Wars names",
        "description": "Returns a list of unique generated names matching the requested species, era, gender, style preset, syllable count, and harshness. Pass an optional `seed` for reproducible results.",
        "operationId": "generateNames",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/GenerateNamesRequest" },
              "examples": {
                "jediBatch": {
                  "summary": "Five Jedi names",
                  "value": { "species": "jedi", "preset": "heroic", "count": 5, "gender": "neutral", "era": "clone-wars" }
                },
                "sithDark": {
                  "summary": "Dark Sith lord",
                  "value": { "species": "sith", "preset": "dark", "count": 3, "harshness": 85 }
                },
                "mandalorianFemale": {
                  "summary": "Female Mandalorian",
                  "value": { "species": "mandalorian", "gender": "female", "era": "imperial", "count": 10 }
                },
                "reproducible": {
                  "summary": "Reproducible run via seed",
                  "value": { "species": "human", "count": 5, "seed": "my-campaign-seed-001" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully generated names",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GenerateNamesResponse" }
              }
            }
          },
          "400": {
            "description": "Invalid request (unknown species/preset or malformed JSON body)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "405": {
            "description": "Method not allowed. Use POST or GET.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Species": {
        "type": "string",
        "description": "Star Wars species or naming category.",
        "enum": [
          "human", "twilek", "wookiee", "zabrak", "mandalorian", "droid",
          "sith", "jedi", "hutt", "rodian", "moncalamari", "chiss",
          "togruta", "gamorrean", "planet"
        ]
      },
      "Preset": {
        "type": "string",
        "description": "Stylistic preset that biases consonants, vowels, and suffixes.",
        "enum": ["classic", "dark", "heroic", "droid", "ancient", "pirate"]
      },
      "Gender": {
        "type": "string",
        "description": "Gender bias for prefix and suffix selection.",
        "enum": ["male", "female", "neutral"]
      },
      "Era": {
        "type": "string",
        "description": "Star Wars era that adds period-appropriate naming tweaks.",
        "enum": ["old-republic", "clone-wars", "imperial", "new-republic"]
      },
      "GenerateNamesRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "species":       { "$ref": "#/components/schemas/Species", "default": "human" },
          "preset":        { "$ref": "#/components/schemas/Preset",  "default": "classic" },
          "gender":        { "$ref": "#/components/schemas/Gender",  "default": "neutral" },
          "era":           { "$ref": "#/components/schemas/Era",     "default": "imperial" },
          "count":         { "type": "integer", "minimum": 1, "maximum": 50, "default": 5, "description": "How many unique names to return." },
          "syllableCount": { "type": "integer", "minimum": 2, "maximum": 5,  "default": 3, "description": "Approximate syllables per generated name." },
          "harshness":     { "type": "integer", "minimum": 0, "maximum": 100, "default": 50, "description": "0 = soft/flowing phonetics, 100 = harsh/percussive phonetics." },
          "seed":          { "type": "string", "description": "Optional seed string for deterministic, reproducible output." }
        }
      },
      "GenerateNamesResponse": {
        "type": "object",
        "required": ["names", "meta"],
        "properties": {
          "names": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Generated unique names. Length may be less than `count` if the requested combination is too constrained.",
            "example": ["Kael Sunrider", "Mira Vos", "Tarin Sol", "Lyra Keth", "Davin Or"]
          },
          "meta": {
            "type": "object",
            "required": ["species", "preset", "gender", "era", "syllableCount", "harshness", "count", "seed"],
            "properties": {
              "species":       { "$ref": "#/components/schemas/Species" },
              "preset":        { "$ref": "#/components/schemas/Preset"  },
              "gender":        { "$ref": "#/components/schemas/Gender"  },
              "era":           { "$ref": "#/components/schemas/Era"     },
              "syllableCount": { "type": "integer" },
              "harshness":     { "type": "integer" },
              "count":         { "type": "integer", "description": "Actual number of names returned." },
              "seed":          { "type": "string",  "description": "Seed used (auto-generated UUID if none was provided)." }
            }
          }
        }
      },
      "ApiSchema": {
        "type": "object",
        "properties": {
          "name":      { "type": "string", "example": "Star Wars Name Generator API" },
          "version":   { "type": "string", "example": "1.0.0" },
          "endpoints": { "type": "object", "additionalProperties": true }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string", "example": "Unknown species \"klingon\". Valid: human, twilek, wookiee, ..." }
        }
      }
    }
  }
}