增加 FastAPI docs 功能开关和 docs 页面描述

1. 为 FastAPI 的文档功能增加显示开关，允许从 WebUI 修改；
2. 在 docs 页面增加了项目的简要描述和引导。

CHANGELOG.md

@@ -7,9 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 6 种更新类别：Added、Changed、Deprecated、Removed、Fixed、Security。
 
-## [Unreleased]
+## [0.1.5] - 2026-04-28
 
-等待中...
+### Added
+
+- 增加开关 FastAPI 内置文档功能的选项。在此前，文档功能一直默认开启。
+
+### Changed
+
+- WebUI 版本升级至 1.1.0
+    - 增加开关 FastAPI `/docs` 文档端点的设置项。
+    - 删除「重启」和「关闭」Suan API 的预留按钮，因为技术上这难以实现。
 
 ## [0.1.4] - 2026-04-26
 

README.md

@@ -12,12 +12,18 @@ NJUPT Suan API 是一个 FastAPI 项目，目标在于实现对 NJUPT（南京
 
 ## 功能
 
-| 计划功能（芒果画饼中）   | 支持进度             |
+| 计划功能（芒果画饼中）       | 支持进度 |
-|---------------|------------------|
+|-------------------|------|
-| 教务系统 - 课程表获取  | ✅                |
+| 教务系统 - 课程表获取      | ✅    |
-| 教务系统 - 课程获取   | ⌛️               |
+| 教务系统 - 课程获取       | ⌛️   |
-| 教务系统 - 成绩获取   | ⌛️               |
+| 教务系统 - 成绩获取       | ⌛️   |
-| 体育部系统 - 早锻炼获取 | ❌（无从破解微信小程序 QAQ） |
+| 教务系统 - 课程表 - 日历订阅 | ⌛️   |
+| 体育部系统 - 早锻炼获取     | ❌    |
+
+| 优化待办          | 支持进度 |
+|---------------|------|
+| 自定义课程表 CSS 样式 | ⌛️   |
+| 生成的静态资源有效期管理  | ⌛️   |
 
 ## 运行
 

src/njupt_suan_api/api/baselib/config.py

@@ -61,6 +61,7 @@ class Config:
         doc_system["port"] = 8000
         doc_system["reload"] = False
         doc_system["public_host"] = "http://127.0.0.1:8000"
+        doc_system["docs"] = True
 
         doc_schedule["playwright_headless"] = True
         doc_schedule["jwxt_login_method"] = "sso"

src/njupt_suan_api/server.py

@@ -24,10 +24,36 @@ from njupt_suan_api.router.enhance import ReturnDto, create_db_and_tables
 
 DATA_DIR = Path.cwd() / "data"
 
+description = """
+🚀 NJUPT Suan API 的 API 文档在此。你也可以直接在此处测试 API。
+
+**NJUPT Suan API** 是一个为南京邮电大学（NJUPT）开发的项目。
+
+**项目** -
+[GitHub](https://github.com/mangofanfan/njupt-suan-api) |
+[Mango Gitea](https://gitea.mangofanfan.cn/SuanDev/njupt-suan-api) |
+[文档](https://suan.mangofanfan.cn)
+
+**文档** - [SwaggerUI](/docs) | [Redoc](/redoc) | [openapi.json](/openapi.json)
+
+### 如果您是访客
+
+部分 **admin** 分组的端点需要身份验证才能调用，它们一般会被标记。
+
+你可以在这里查看所有端点的详细信息，如果你需要进行针对 Suan API 的开发的话，这一定会对你有所帮助。
+
+### 如果您是管理员
+
+文档功能作为 FastAPI 的特色功能默认开启。
+
+如果你需要，在 Suan API 的设置中可以选择关闭文档功能。
+"""
+
+config.sync_load_json()
+
 
 async def toml_watcher() -> None:
     """配置文件监听器"""
-    await config.load_json()
     async for change in awatch(DATA_DIR / "config.json"):
         logger.info(f"配置文件更新，重新加载 | {change=}")
         await config.load_json()
@@ -48,7 +74,20 @@ async def life_span(_: FastAPI) -> AsyncGenerator[None, None]:
         logger.info("配置文件监听任务已结束。")
 
 
-app = FastAPI(lifespan=combine_lifespans(life_span, mcp_app.lifespan))
+# 文档功能是对 FastAPI app 实例进行配置的
+enable_docs = config.get("system", "docs", True)
+logger.debug(f"FastAPI 文档功能状态 - {enable_docs=}")
+
+app = FastAPI(
+    title="njupt-suan-api",
+    lifespan=combine_lifespans(life_span, mcp_app.lifespan),
+    description=description,
+    docs_url="/docs" if enable_docs else None,
+    redoc_url="/redoc" if enable_docs else None,
+    openapi_url="/openapi.json" if enable_docs else None,
+    version=__version__,
+    license_info={"name": "MIT", "identifier": "MIT"},
+)
 
 
 @app.middleware("http")

uv.lock

@@ -701,7 +701,7 @@ wheels = [
 
 [[package]]
 name = "njupt-suan-api"
-version = "0.1.3"
+version = "0.1.5"
 source = { editable = "." }
 dependencies = [
     { name = "aiofiles" },