{
  "openapi": "3.0.3",
  "info": {
    "title": "Finansordbok API",
    "description": "Offentlig API for Norges største finansordbok. Gir tilgang til korte definisjoner, søk, kategorier og relaterte begreper.\n\nKrever API-nøkkel. Få din nøkkel på Min side.",
    "version": "1.0.0",
    "contact": {
      "email": "api@finansordbok.no"
    }
  },
  "servers": [
    {
      "url": "v1",
      "description": "Relativ til denne spec-ens plassering (…/api/)"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "query",
        "name": "key",
        "description": "Din API-nøkkel (sk_live_...). Få den på Min side."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string", "example": "RATE_LIMITED" },
              "message": { "type": "string", "example": "For mange forespørsler." }
            }
          }
        }
      },
      "TermSummary": {
        "type": "object",
        "properties": {
          "term": { "type": "string", "example": "Aksje" },
          "slug": { "type": "string", "example": "aksje" },
          "short_definition": { "type": "string", "example": "Eierandel i et selskap." },
          "language_code": { "type": "string", "example": "no" },
          "category": { "type": "string", "example": "Aksjer og børs" },
          "difficulty": { "type": "string", "example": "beginner" },
          "aliases": { "type": "array", "items": { "type": "string" }, "example": ["share"] },
          "key_takeaways": { "type": "array", "items": { "type": "string" }, "example": ["Aksjer gir eierandel"] }
        }
      },
      "TermDetail": {
        "type": "object",
        "properties": {
          "term": { "type": "string" },
          "slug": { "type": "string" },
          "short_definition": { "type": "string" },
          "language_code": { "type": "string" },
          "category": { "type": "string" },
          "subcategory": { "type": "string" },
          "difficulty": { "type": "string" },
          "aliases": { "type": "array", "items": { "type": "object" } },
          "key_takeaways": { "type": "array", "items": { "type": "string" } },
          "faq": { "type": "array", "items": { "type": "object" } },
          "related_terms": { "type": "array", "items": { "type": "object" } },
          "formula": { "type": "string", "nullable": true }
        }
      },
      "SuccessResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": { "type": "object" },
          "meta": {
            "type": "object",
            "properties": {
              "requested_at": { "type": "string", "format": "date-time" },
              "execution_ms": { "type": "integer" },
              "api_version": { "type": "string" }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/sok": {
      "get": {
        "summary": "Søk etter begreper",
        "description": "Fritekstsøk på tvers av alle publiserte begreper. Søker i term og short_definition.",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Søketekst", "example": "aksje" },
          { "name": "lang", "in": "query", "schema": { "type": "string", "enum": ["no", "en"], "default": "no" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 100 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } },
          { "$ref": "#/components/securitySchemes/ApiKeyAuth" }
        ],
        "responses": {
          "200": { "description": "Søkeresultater", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } },
          "400": { "description": "Mangler søkeparameter" },
          "401": { "description": "Ugyldig nøkkel" },
          "429": { "description": "Rate limit" }
        }
      }
    },
    "/begrep/{slug}": {
      "get": {
        "summary": "Hent ett begrep",
        "description": "Returnerer kortdefinisjon og metadata for ett begrep. Ingen full artikkel.",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "aksje" },
          { "name": "lang", "in": "query", "schema": { "type": "string", "enum": ["no", "en"], "default": "no" } },
          { "$ref": "#/components/securitySchemes/ApiKeyAuth" }
        ],
        "responses": {
          "200": { "description": "Begrep funnet" },
          "404": { "description": "Ikke funnet" }
        }
      }
    },
    "/begrep/{slug}/relatert": {
      "get": {
        "summary": "Relaterte begreper",
        "description": "Henter relaterte begreper for et gitt begrep.",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "aksje" },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "no" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 20 } },
          { "$ref": "#/components/securitySchemes/ApiKeyAuth" }
        ],
        "responses": { "200": { "description": "Liste over relaterte begreper" } }
      }
    },
    "/kategorier": {
      "get": {
        "summary": "Alle kategorier",
        "description": "Henter alle tilgjengelige kategorier.",
        "parameters": [
          { "name": "lang", "in": "query", "schema": { "type": "string", "enum": ["no", "en"], "default": "no" } },
          { "$ref": "#/components/securitySchemes/ApiKeyAuth" }
        ],
        "responses": { "200": { "description": "Kategoriliste" } }
      }
    },
    "/kategori/{id}": {
      "get": {
        "summary": "Begreper i kategori",
        "description": "Henter alle begreper i en gitt kategori.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "stocks" },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "no" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } },
          { "$ref": "#/components/securitySchemes/ApiKeyAuth" }
        ],
        "responses": { "200": { "description": "Liste over begreper" } }
      }
    },
    "/tilfeldig": {
      "get": {
        "summary": "Tilfeldig begrep",
        "description": "Returnerer et tilfeldig begrep fra ordboken.",
        "parameters": [
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "no" } },
          { "$ref": "#/components/securitySchemes/ApiKeyAuth" }
        ],
        "responses": { "200": { "description": "Tilfeldig begrep" } }
      }
    },
    "/statistikk": {
      "get": {
        "summary": "Global statistikk",
        "description": "Returnerer metadata om ordboken: antall begreper, kategorier, språk.",
        "parameters": [
          { "$ref": "#/components/securitySchemes/ApiKeyAuth" }
        ],
        "responses": { "200": { "description": "Ordbok-statistikk" } }
      }
    },
    "/min-nokkel": {
      "get": {
        "summary": "Din nøkkel-statistikk",
        "description": "Returnerer bruksstatistikk for din API-nøkkel.",
        "parameters": [
          { "$ref": "#/components/securitySchemes/ApiKeyAuth" }
        ],
        "responses": { "200": { "description": "Nøkkel-statistikk" } }
      }
    }
  }
}