从0到1设计OI Wiki开放接口：让竞赛知识像API一样触手可及

为什么需要OI Wiki开放接口？

你是否曾遇到这些痛点：想开发竞赛刷题APP却苦于没有结构化题库数据？制作算法学习小程序时无法实时获取最新知识点？OI Wiki作为国内最全面的算法竞赛知识库（项目主页），其海量优质内容（如动态规划专题、图论算法）长期以来只能通过网页浏览。本文将系统设计一套开放API接口，让第三方应用能轻松调用这些竞赛知识数据。

接口设计原则与整体架构

核心设计理念

OI Wiki API遵循"最小可用"原则，优先覆盖高频需求场景：

• 知识结构化：将Markdown文档转换为机器可读的JSON格式
• 版本控制：采用/v1/作为基础路径，预留迭代空间
• 缓存策略：热门接口（如算法分类列表）设置5分钟缓存

系统架构图

graph TD
    A[客户端应用] -->|HTTP请求| B[API网关]
    B --> C{认证中间件}
    C -->|已授权| D[业务逻辑层]
    C -->|未授权| E[返回401]
    D --> F[数据转换器]
    F --> G[Markdown文档库]
    G --> H[JSON响应生成]
    H --> A

核心接口规范

1. 知识点查询接口

请求示例：

GET /v1/knowledge?category=dp&title=knapsack

响应格式：

{
  "id": "dp-knapsack-001",
  "title": "背包问题",
  "content": {
    "description": "动态规划经典问题...",
    "formula": "f[i][j] = max(f[i-1][j], f[i-1][j-w[i]] + v[i])",
    "examples": [
      {"input": "n=3, W=5", "output": "max=8"}
    ]
  },
  "related": ["unbounded-knapsack", "group-knapsack"]
}

数据来源：docs/dp/knapsack.md

2. 算法分类接口

请求示例：

GET /v1/categories?parent=graph

响应格式：

{
  "parent": "图论",
  "children": [
    {"id": "graph-bfs", "name": "广度优先搜索", "doc_count": 12},
    {"id": "graph-dfs", "name": "深度优先搜索", "doc_count": 8},
    {"id": "graph-mst", "name": "最小生成树", "doc_count": 5}
  ]
}

数据来源：docs/graph/index.md

实现方案与技术选型

文档解析模块

采用Python Markdown解析库，关键代码片段：

import markdown
from markdown.extensions.toc import TocExtension

def parse_knowledge(path):
    with open(path, 'r', encoding='utf-8') as f:
        text = f.read()
    html = markdown.markdown(text, extensions=[
        TocExtension(permalink=True),
        'extra', 'codehilite'
    ])
    # 提取标题、公式、示例等结构化数据
    return extract_structure(html)

类似实现参考：scripts/check-characters.py

部署架构

推荐使用Docker容器化部署：

FROM nginx:alpine
COPY ./api /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf

部署指南参考：docs/intro/docker-deploy.md

应用场景与调用示例

移动学习APP集成

教育类APP可通过API实现：

• 实时获取最新算法讲解
• 离线缓存重点知识点
• 个性化推荐学习路径

命令行查询工具

# 查询快速排序算法
curl https://api.oi-wiki.com/v1/knowledge?title=quick-sort

接口文档与开发者资源

• 完整接口文档：待开发（计划基于docs/intro/format.md规范）
• SDK下载：提供Python/Java版本（开发中）
• 贡献指南：CONTRIBUTING.md

未来扩展计划

1. 高级搜索功能：支持公式、复杂度等参数检索
2. 用户反馈接口：允许第三方应用提交内容纠错建议
3. 实时更新通知：通过WebHook推送文档更新事件

通过这套API设计，OI Wiki的知识体系将突破网页边界，赋能更多竞赛学习工具的创新开发。无论是教育平台、刷题软件还是智能问答系统，都能便捷地集成权威的算法竞赛知识。

本文档基于OI Wiki现有知识结构设计，所有接口均为概念性方案。实际开发需参考项目贡献规范。