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™ is property of Lucasfilm Ltd. / The Walt Disney Company.
    This is an unaffiliated fan project.
  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
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
      operationId: getApiSchema
      responses:
        "200":
          description: API schema document
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ApiSchema" }
    post:
      tags: [Names]
      summary: Generate Star Wars names
      operationId: generateNames
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: "#/components/schemas/GenerateNamesRequest" }
      responses:
        "200":
          description: Successfully generated names
          content:
            application/json:
              schema: { $ref: "#/components/schemas/GenerateNamesResponse" }
        "400":
          description: Invalid request
          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
      enum: [human, twilek, wookiee, zabrak, mandalorian, droid, sith, jedi, hutt, rodian, moncalamari, chiss, togruta, gamorrean, planet]
    Preset:
      type: string
      enum: [classic, dark, heroic, droid, ancient, pirate]
    Gender:
      type: string
      enum: [male, female, neutral]
    Era:
      type: string
      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 }
        syllableCount: { type: integer, minimum: 2, maximum: 5,   default: 3 }
        harshness:     { type: integer, minimum: 0, maximum: 100, default: 50 }
        seed:          { type: string, description: Optional seed for reproducible output }
    GenerateNamesResponse:
      type: object
      required: [names, meta]
      properties:
        names:
          type: array
          items: { type: string }
        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 }
            seed:          { type: string }
    ApiSchema:
      type: object
      properties:
        name:      { type: string }
        version:   { type: string }
        endpoints: { type: object, additionalProperties: true }
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error: { type: string }