SuanDocs/suan-api/api-docs.md

API 文档

Suan API 公开的 API 端点为 /api，不需要身份验证即可调用。

在 WebUI 中的「课表管理」页面可以查看该版本的 Suan API 提供的公共 API 信息，在 FastAPI 自带的 /docs 端点中也可以查看所有 API 的文档。本文档记录的信息默认为最新版本的，并且进行稍详细的介绍，如果你没有使用最新版本的话，可能会有不一样。

返回值

大部分端点都会返回统一的结构化数据。在 Suan API 内部的定义如下：

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