{
  "openapi": "3.1.0",
  "info": {
    "title": "JX3TNT PVE 权威天梯榜开放接口",
    "version": "1.0.0-draft",
    "description": "面向剑三机器人和社区工具开发者，免费提供正式榜单、公开招募和 Token 用量查询。所有业务接口均为只读查询。"
  },
  "servers": [{ "url": "https://api.jx3tnt.com" }],
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/v1/recruitments/today": {
      "get": {
        "summary": "查询今日正在招募列表",
        "operationId": "listTodayRecruitments",
        "responses": {
          "200": { "$ref": "#/components/responses/RecruitmentList" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/recruitments/long-term": {
      "get": {
        "summary": "查询长期招募列表",
        "operationId": "listLongTermRecruitments",
        "responses": {
          "200": { "$ref": "#/components/responses/RecruitmentList" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/leaderboards/{leaderboardKind}": {
      "get": {
        "summary": "查询正式榜单前 100",
        "operationId": "listLeaderboard",
        "parameters": [
          { "name": "leaderboardKind", "in": "path", "required": true, "description": "要查询的榜单类型。", "schema": { "$ref": "#/components/schemas/LeaderboardKind" } },
          { "name": "dungeonId", "in": "query", "description": "只查看指定副本。", "schema": { "type": "string", "maxLength": 100 } },
          { "name": "bossId", "in": "query", "description": "只查看指定 Boss。", "schema": { "type": "string", "maxLength": 100 } },
          { "name": "kungfuId", "in": "query", "description": "只查看指定心法 ID。", "schema": { "type": "string", "maxLength": 100 } },
          { "name": "kungfuName", "in": "query", "description": "只查看指定心法名称。", "schema": { "type": "string", "maxLength": 100 } },
          { "name": "limit", "in": "query", "description": "返回数量，默认 100，最多 100。", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/RankingList" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/characters/rankings": {
      "get": {
        "summary": "按服务器和角色名精确查询各榜排名",
        "operationId": "listCharacterRankings",
        "parameters": [
          { "name": "serverName", "in": "query", "required": true, "description": "角色所在服务器，必须精确填写。", "schema": { "type": "string", "maxLength": 100 } },
          { "name": "characterName", "in": "query", "required": true, "description": "角色名称，必须精确填写。", "schema": { "type": "string", "maxLength": 100 } },
          { "name": "kungfuId", "in": "query", "description": "只查看指定心法 ID 的榜单结果。", "schema": { "type": "string", "maxLength": 100 } },
          { "name": "kungfuName", "in": "query", "description": "只查看指定心法名称的榜单结果。", "schema": { "type": "string", "maxLength": 100 } }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/RankingList" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "summary": "查询当前 Token 的今日和本月用量",
        "operationId": "getUsage",
        "responses": {
          "200": { "description": "返回今日、本月调用次数和对应额度。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JX3TNT API Token" }
    },
    "schemas": {
      "LeaderboardKind": {
        "type": "string",
        "enum": ["grandmaster_hero", "grandmaster_peak", "mingxia_regular_dps", "mingxia_tank_dps", "mingxia_healer_hps", "team_top10_top100", "team_speed_hero"]
      },
      "Character": {
        "type": ["object", "null"],
        "properties": {
          "serverName": { "type": ["string", "null"] },
          "characterName": { "type": ["string", "null"] },
          "kungfuId": { "type": ["string", "null"] },
          "kungfuName": { "type": ["string", "null"] },
          "kungfuIconId": { "type": ["string", "null"] }
        },
        "additionalProperties": false
      },
      "Team": {
        "type": ["object", "null"],
        "properties": {
          "teamName": { "type": ["string", "null"] },
          "homeServer": { "type": ["string", "null"] },
          "badge": { "type": ["string", "null"] }
        },
        "additionalProperties": false
      },
      "Ranking": {
        "type": "object",
        "required": ["leaderboardKind", "rank", "value"],
        "properties": {
          "leaderboardKind": { "$ref": "#/components/schemas/LeaderboardKind" },
          "seasonId": { "type": ["string", "null"] },
          "dungeonId": { "type": ["string", "null"] },
          "bossId": { "type": ["string", "null"] },
          "rank": { "type": "integer", "minimum": 1 },
          "value": { "type": "number" },
          "subjectType": { "type": ["string", "null"], "enum": ["character", "team", null] },
          "character": { "$ref": "#/components/schemas/Character" },
          "team": { "$ref": "#/components/schemas/Team" },
          "reportUrl": { "type": ["string", "null"] }
        },
        "additionalProperties": false
      },
      "Recruitment": {
        "type": "object",
        "properties": {
          "channel": { "type": ["string", "null"] },
          "status": { "type": ["string", "null"] },
          "title": { "type": ["string", "null"] },
          "seasonId": { "type": ["string", "null"] },
          "dungeonIds": { "type": "array", "items": { "type": "string" } },
          "team": { "type": ["object", "null"] },
          "requirements": { "type": "object" },
          "sessions": { "type": "array", "items": { "type": "object" } },
          "earliestStartsAt": { "type": ["string", "null"], "format": "date-time" },
          "posterUrl": { "type": ["string", "null"] }
        },
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "required": ["ok", "error"],
        "properties": {
          "ok": { "const": false },
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }
          }
        }
      },
      "UsageResponse": {
        "type": "object",
        "properties": {
          "ok": { "const": true },
          "billingMode": { "type": "string", "enum": ["free", "metered"] },
          "data": {
            "type": "object",
            "properties": {
              "dailyQuota": { "type": "integer" }, "dailyUsed": { "type": "integer" },
              "monthlyQuota": { "type": "integer" }, "monthlyUsed": { "type": "integer" }
            }
          }
        }
      }
    },
    "responses": {
      "RecruitmentList": { "description": "返回当前可以公开查看的招募列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Recruitment" } } } } } } },
      "RankingList": { "description": "返回正式榜单数据及本次榜单的版本和生成时间。", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "snapshotVersion": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Ranking" } } } } } } },
      "BadRequest": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unauthorized": { "description": "Token 缺失、无效、过期或已停用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Forbidden": { "description": "当前 Token 没有开通这个查询权限。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "调用过于频繁，或本日／本月额度已经用完。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unavailable": { "description": "服务或正式榜单数据暂时不可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  }
}