增加 API 文档页面

增加 API 文档 和 Playwright 页面。

.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' },
         ]
       },

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 进行截图，在服务器上对于性能开销稍大，因此不会默认启用。

suan-api/playwright.md

@@ -1,3 +1,9 @@
 # Playwright
 
 Playwright 是一个用于浏览器自动化的工具，Suan API 通过 playwright 来规避教务系统和统一身份认证的反爬虫措施，顺便用它来截图。
+
+## 安装
+
+Playwright 需要额外的安装步骤，在 [部署](deploy.md) 中已经说明。
+
+在开发中芒果直接使用的是 chromium，暂未测试其他选项（firefox），不过我估计应该也没什么问题就是了~