洛谷 API 文档

洛谷（luogu.com.cn）非官方 API 的多形态文档与测试套件

同一套 API 以三种形态保持同步：人工编写的 Markdown 文档、机器可读的 OpenAPI 3.1 规范、以及针对线上 API 的 Python 测试套件。

仓库结构

├── docs/                    # Markdown 文档 + luogu-api.d.ts（git submodule）
├── openapi/                 # OpenAPI 3.1 规范
│   ├── openapi.yaml         # 入口，聚合 paths/ 与 components/
│   ├── paths/*.yaml         # 各分类端点定义
│   └── components/schemas.yaml
├── luogutests/              # Python 测试套件（requests + uv）
└── pyproject.toml

docs/ 是 git submodule，指向 Enigma-Soul/luogu-api-markdown——上游 0f-0b/luogu-api-docs 的人工编写镜像。docs/*.md、docs/luogu-api.d.ts、docs/deno.json 均来自此子模块，本仓库根目录不再保留副本。

克隆时带上子模块：

git clone --recurse-submodules https://github.com/Enigma-Soul/luogu-api-openapi.git
# 已克隆的仓库补齐子模块
git submodule update --init docs

快速开始

测试套件通过 uv 运行，需在项目根目录放置 cookie.json（浏览器导出的 Cookie 数组）。

uv run luogutest                     # 运行全部测试
uv run python luogutests/problem.py  # 运行单个模块
uv run python luogutests/article.py list mine  # 运行模块内指定 API

通用约定

Note

• Base URL：https://www.luogu.com.cn
• 文本编码 UTF-8
• user-agent 不能含子串 python-requests（忽略大小写），也不能以 mozilla/ 开头

Important

非 GET 请求需附带 referer: https://www.luogu.com.cn/ 与 x-csrf-token 头（CSRF 令牌从页面 HTML 的 <meta name="csrf-token"> 获取）。

响应主体有两种包装，请求时需对应声明：

响应类型	触发方式	数据位置
DataResponse	参数 _contentOnly 或头 x-luogu-type: content-only	.currentData
LentilleDataResponse	头 x-lentille-request: content-only	.data

文档目录

完整文档见 docs/index.md，涵盖：

题目 · 题单 · 比赛 · 记录 · 讨论 · 动态 · 用户 · 团队 · 私信 · 主题 · 图片 · IDE · 剪贴板 · 专栏 · 博客 · 身份验证 · 杂项 · WebSocket

许可证

UNLICENSE