From 6e4525a9b98d3edd988e9258c7636f7d7e01c8ed Mon Sep 17 00:00:00 2001
From: MangoFanFanw <mangofanfanw@icloud.com>
Date: Wed, 22 Apr 2026 15:31:04 +0800
Subject: [PATCH] =?UTF-8?q?=E5=A2=9E=E5=8A=A0=20API=20=E6=96=87=E6=A1=A3?=
 =?UTF-8?q?=E9=A1=B5=E9=9D=A2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

增加 API 文档 和 Playwright 页面。
---
 .vitepress/config.mts  |  1 +
 suan-api/api-docs.md   | 22 ++++++++++++++++++++++
 suan-api/playwright.md |  8 +++++++-
 3 files changed, 30 insertions(+), 1 deletion(-)
 create mode 100644 suan-api/api-docs.md

diff --git a/.vitepress/config.mts b/.vitepress/config.mts
index 4cac82c..4200b28 100644
--- a/.vitepress/config.mts
+++ b/.vitepress/config.mts
@@ -17,6 +17,7 @@ export default defineConfig({
           { text: '介绍', link: '/suan-api/introduction' },
           { text: '部署', link: '/suan-api/deploy' },
           { text: 'Playwright', link: '/suan-api/playwright' },
+          { text: 'API 文档', link: '/suan-api/api-docs' },
           { text: 'LLM 工具', link: '/suan-api/llm-tools' },
         ]
       },
diff --git a/suan-api/api-docs.md b/suan-api/api-docs.md
new file mode 100644
index 0000000..8b605b7
--- /dev/null
+++ b/suan-api/api-docs.md
@@ -0,0 +1,22 @@
+# API 文档
+
+Suan API 公开的 API 端点为 `/api`，不需要身份验证即可调用。
+
+在 WebUI 中的「**课表管理**」页面可以查看该版本的 Suan API 提供的公共 API 信息，在 FastAPI 自带的 `/docs` 端点中也可以查看所有 API 的文档。本文档记录的信息默认为最新版本的，并且进行稍详细的介绍，如果你没有使用最新版本的话，可能会有不一样。
+
+## 返回值
+
+大部分端点都会返回统一的结构化数据。在 Suan API 内部的定义如下：
+
+```python
+# router/enhance/lib.py
+class ReturnDto(BaseModel):
+    success: bool
+    message: str | None = None
+    result: Any | None = None
+    img_url: str | None = None
+```
+
+请求得到的响应的状态码也是很重要的信息。对于大部分端点来说，状态码反映的是服务器内部是否出现意料之外的错误（`5XX`），而返回值中的 `success` 字段表示的是请求在业务上是否成功。
+
+`img_url` 是否存在是根据请求时是否有 `img: True` 来决定的，默认为 False。生成图片需要使用 Playwright 进行截图，在服务器上对于性能开销稍大，因此不会默认启用。
diff --git a/suan-api/playwright.md b/suan-api/playwright.md
index 35ef98d..3ffed03 100644
--- a/suan-api/playwright.md
+++ b/suan-api/playwright.md
@@ -1,3 +1,9 @@
 # Playwright
 
-Playwright 是一个用于浏览器自动化的工具，Suan API 通过 playwright 来规避教务系统和统一身份认证的反爬虫措施，顺便用它来截图。
\ No newline at end of file
+Playwright 是一个用于浏览器自动化的工具，Suan API 通过 playwright 来规避教务系统和统一身份认证的反爬虫措施，顺便用它来截图。
+
+## 安装
+
+Playwright 需要额外的安装步骤，在 [部署](deploy.md) 中已经说明。
+
+在开发中芒果直接使用的是 chromium，暂未测试其他选项（firefox），不过我估计应该也没什么问题就是了~