{
  "openapi": "3.1.0",
  "info": {
    "title": "ip.fs.kg",
    "version": "1.0.0",
    "summary": "Fast, private, and secure IP intelligence — 无需密钥的公网 IP 情报接口",
    "description": "三个公开接口，全部免鉴权、CORS 全开、服务端不落库。数据由 Cloudflare 边缘节点直接从访客连接中读取（request.cf），不经过任何第三方地理接口。",
    "contact": { "name": "ip.fs.kg", "url": "https://ip.fs.kg/contact" },
    "license": { "name": "Public endpoints, no key required", "identifier": "NOASSERTION" }
  },
  "servers": [{ "url": "https://ip.fs.kg", "description": "生产环境" }],
  "tags": [
    { "name": "lookup", "description": "读取访客自身的网络信息" }
  ],
  "paths": {
    "/": {
      "get": {
        "tags": ["lookup"],
        "operationId": "plainTextIp",
        "summary": "纯文本 IP",
        "description": "命令行客户端（curl / wget / httpie / PowerShell 等）访问时返回一行纯文本 IP；浏览器访问返回完整 HTML 界面。判断依据是 User-Agent 与 Accept 头。",
        "responses": {
          "200": {
            "description": "纯文本形式的公网 IP，或 HTML 界面",
            "content": {
              "text/plain": {
                "schema": { "type": "string", "examples": ["203.0.113.42"] }
              },
              "text/html": { "schema": { "type": "string" } }
            }
          },
          "301": { "description": "缺少协议头时重定向到 HTTPS；curl 需要加 -L 才能跟过去" }
        }
      }
    },
    "/json": {
      "get": {
        "tags": ["lookup"],
        "operationId": "getJson",
        "summary": "完整情报（JSON）",
        "description": "返回与 /api/whoami 完全相同的字段。路径更短，且不落在 /api/ 下（该前缀在 robots.txt 中被 Disallow）。",
        "parameters": [
          {
            "name": "pretty",
            "in": "query",
            "required": false,
            "description": "存在即缩进两格输出，值本身不参与判断（?pretty 与 ?pretty=1 等价）",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "访客的网络信息",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Whoami" }
              }
            }
          }
        }
      }
    },
    "/api/whoami": {
      "get": {
        "tags": ["lookup"],
        "operationId": "getWhoami",
        "summary": "完整情报（与 /json 同源）",
        "description": "首页脚本使用的入口，字段与 /json 完全一致。可以带时间戳参数绕开中间缓存。",
        "responses": {
          "200": {
            "description": "访客的网络信息",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Whoami" }
              }
            }
          },
          "404": { "description": "纯静态部署（没有 Pages Functions）时该路径不存在" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Whoami": {
        "type": "object",
        "description": "全部字段都可能为 null —— 边缘节点给不出细粒度信息时不会编造。",
        "properties": {
          "ip": { "type": ["string", "null"], "description": "访客公网地址", "examples": ["203.0.113.42"] },
          "type": { "type": ["string", "null"], "enum": ["IPv4", "IPv6", null], "description": "地址协议版本" },
          "asn": { "type": ["integer", "null"], "description": "自治系统号", "examples": [4134] },
          "org": { "type": ["string", "null"], "description": "网络组织名" },
          "isp": { "type": ["string", "null"], "description": "运营商名，与 org 同源" },
          "city": { "type": ["string", "null"], "description": "城市" },
          "region": { "type": ["string", "null"], "description": "省 / 州" },
          "country": { "type": ["string", "null"], "description": "两位国家码", "examples": ["CN"] },
          "country_code": { "type": ["string", "null"], "description": "与 country 相同，兼容旧调用方" },
          "continent": { "type": ["string", "null"], "description": "大洲代码", "examples": ["AS"] },
          "latitude": { "type": ["string", "number", "null"], "description": "纬度（城市级近似）。边缘给的是数字字符串，调用方请自行 parseFloat" },
          "longitude": { "type": ["string", "number", "null"], "description": "经度（城市级近似）。同样可能是数字字符串" },
          "postal": { "type": ["string", "null"], "description": "邮政编码" },
          "timezone": { "type": ["string", "null"], "description": "IANA 时区名", "examples": ["Asia/Shanghai"] },
          "isEu": { "type": ["boolean", "null"], "description": "是否位于欧盟境内" },
          "colo": { "type": ["string", "null"], "description": "处理本次请求的边缘节点三字码", "examples": ["HKG"] },
          "tlsVersion": { "type": ["string", "null"], "description": "协商出的 TLS 版本", "examples": ["TLSv1.3"] },
          "tlsCipher": { "type": ["string", "null"], "description": "协商出的加密套件" },
          "httpProtocol": { "type": ["string", "null"], "enum": ["HTTPS", "HTTP", null] },
          "acceptLanguage": { "type": ["string", "null"], "description": "请求头 Accept-Language 的首值" },
          "edge": { "type": "boolean", "description": "恒为 true，标记数据来自边缘直读" },
          "ts": { "type": "integer", "description": "毫秒时间戳，每次请求都不同" }
        }
      }
    }
  }
}