{
  "openapi": "3.0.3",
  "info": {
    "title": "fakedata — Fake Data Generator API",
    "description": "Generates realistic-looking but entirely fictional data: full people (name, email, address, phone, company, IP, UUID …) and individual values by type (names, emails, addresses, IPv4/IPv6, MAC, UUID, domain, URL, colour, checksum-valid IBAN and Luhn-valid credit card, lorem text and more). Pure and offline: values come from a seeded PRNG, so passing the same seed reproduces the same output. Locales 'en' and 'de' are supported.",
    "version": "1.0.0"
  },
  "servers": [
    { "url": "https://fakedata.benjamin-dreier.de", "description": "Production" }
  ],
  "paths": {
    "/v1/person": {
      "get": {
        "summary": "Generate one or more fake people",
        "operationId": "person",
        "parameters": [
          { "$ref": "#/components/parameters/N" },
          { "$ref": "#/components/parameters/Seed" },
          { "$ref": "#/components/parameters/Locale" }
        ],
        "responses": {
          "200": {
            "description": "The generated people plus the seed used (so the result can be reproduced).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PersonResponse" },
                "example": {
                  "seed": 42,
                  "locale": "de",
                  "count": 1,
                  "people": [
                    {
                      "first_name": "Lena",
                      "last_name": "Weber",
                      "full_name": "Lena Weber",
                      "email": "lena.weber@example.com",
                      "username": "lena27",
                      "phone": "+49 152 8471023",
                      "birth_date": "1988-04-17",
                      "address": { "street": "Lindenstraße 42", "city": "Leipzig", "zip_code": "04109", "country": "Deutschland" },
                      "company": "Fischer GmbH",
                      "job_title": "Data Analyst",
                      "ipv4": "192.0.2.14",
                      "ipv6": "2001:db8::1",
                      "uuid": "b7e8...-4..."
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid 'n' or 'seed'.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/v1/generate": {
      "get": {
        "summary": "Generate values of a single type",
        "operationId": "generate",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": true,
            "description": "The value type to generate.",
            "schema": {
              "type": "string",
              "enum": [
                "first_name", "last_name", "full_name", "email", "username", "phone",
                "birth_date", "street", "city", "zip", "country", "address", "company",
                "job_title", "ipv4", "ipv6", "mac", "uuid", "domain", "url", "color",
                "bool", "int", "credit_card", "iban", "lorem"
              ]
            },
            "example": "ipv4"
          },
          { "$ref": "#/components/parameters/N" },
          { "$ref": "#/components/parameters/Seed" },
          { "$ref": "#/components/parameters/Locale" }
        ],
        "responses": {
          "200": {
            "description": "The generated values plus the seed used.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GenerateResponse" },
                "example": {
                  "seed": 1,
                  "type": "ipv4",
                  "locale": "en",
                  "count": 3,
                  "values": ["192.0.2.14", "203.0.113.7", "198.51.100.42"]
                }
              }
            }
          },
          "400": {
            "description": "Missing/unknown 'type', or invalid 'n'/'seed'.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/healthz": {
      "get": {
        "summary": "Service health and version",
        "operationId": "health",
        "responses": { "200": { "description": "Service ready." } }
      }
    }
  },
  "components": {
    "parameters": {
      "N": {
        "name": "n",
        "in": "query",
        "required": false,
        "description": "How many items to generate (1-1000).",
        "schema": { "type": "integer", "default": 1, "minimum": 1, "maximum": 1000 },
        "example": 5
      },
      "Seed": {
        "name": "seed",
        "in": "query",
        "required": false,
        "description": "PRNG seed for reproducible output. Omit for a random seed; the seed used is always echoed in the response.",
        "schema": { "type": "integer", "format": "int64" },
        "example": 42
      },
      "Locale": {
        "name": "locale",
        "in": "query",
        "required": false,
        "description": "Data locale for names, cities and streets. 'en' (default) or 'de'.",
        "schema": { "type": "string", "enum": ["en", "de"], "default": "en" },
        "example": "de"
      }
    },
    "schemas": {
      "PersonResponse": {
        "type": "object",
        "required": ["seed", "locale", "count", "people"],
        "properties": {
          "seed": { "type": "integer", "format": "int64", "example": 42 },
          "locale": { "type": "string", "example": "de" },
          "count": { "type": "integer", "example": 1 },
          "people": { "type": "array", "items": { "$ref": "#/components/schemas/Person" } }
        }
      },
      "Person": {
        "type": "object",
        "properties": {
          "first_name": { "type": "string", "example": "Lena" },
          "last_name": { "type": "string", "example": "Weber" },
          "full_name": { "type": "string", "example": "Lena Weber" },
          "email": { "type": "string", "example": "lena.weber@example.com" },
          "username": { "type": "string", "example": "lena27" },
          "phone": { "type": "string", "example": "+49 152 8471023" },
          "birth_date": { "type": "string", "format": "date", "example": "1988-04-17" },
          "address": { "$ref": "#/components/schemas/Address" },
          "company": { "type": "string", "example": "Fischer GmbH" },
          "job_title": { "type": "string", "example": "Data Analyst" },
          "ipv4": { "type": "string", "example": "192.0.2.14" },
          "ipv6": { "type": "string", "example": "2001:db8::1" },
          "uuid": { "type": "string", "format": "uuid" }
        }
      },
      "Address": {
        "type": "object",
        "properties": {
          "street": { "type": "string", "example": "Lindenstraße 42" },
          "city": { "type": "string", "example": "Leipzig" },
          "zip_code": { "type": "string", "example": "04109" },
          "country": { "type": "string", "example": "Deutschland" }
        }
      },
      "GenerateResponse": {
        "type": "object",
        "required": ["seed", "type", "locale", "count", "values"],
        "properties": {
          "seed": { "type": "integer", "format": "int64", "example": 1 },
          "type": { "type": "string", "example": "ipv4" },
          "locale": { "type": "string", "example": "en" },
          "count": { "type": "integer", "example": 3 },
          "values": { "type": "array", "items": {}, "description": "Generated values; each item's shape depends on 'type' (string, integer, boolean or an address object)." }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "example": "unknown type \"teleporter\"" }
        }
      }
    }
  }
}