From 3a38dcab00da3561c1810dd917356b16ac2d4ad0 Mon Sep 17 00:00:00 2001 From: MangoFanFanw Date: Tue, 28 Apr 2026 20:02:05 +0800 Subject: [PATCH] =?UTF-8?q?=E5=A2=9E=E5=8A=A0=20FastAPI=20docs=20=E5=8A=9F?= =?UTF-8?q?=E8=83=BD=E5=BC=80=E5=85=B3=E5=92=8C=20docs=20=E9=A1=B5?= =?UTF-8?q?=E9=9D=A2=E6=8F=8F=E8=BF=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. 为 FastAPI 的文档功能增加显示开关，允许从 WebUI 修改； 2. 在 docs 页面增加了项目的简要描述和引导。 --- CHANGELOG.md | 12 +++++-- README.md | 18 ++++++---- src/njupt_suan_api/api/baselib/config.py | 1 + src/njupt_suan_api/server.py | 43 ++++++++++++++++++++++-- uv.lock | 2 +- 5 files changed, 65 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9d22487..2bb90bc 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 29c7246..bbe6dad 100644 --- a/README.md +++ b/README.md @@ -12,12 +12,18 @@ NJUPT Suan API 是一个 FastAPI 项目，目标在于实现对 NJUPT（南京 ## 功能 -| 计划功能（芒果画饼中） | 支持进度 | -|---------------|------------------| -| 教务系统 - 课程表获取 | ✅ | -| 教务系统 - 课程获取 | ⌛️ | -| 教务系统 - 成绩获取 | ⌛️ | -| 体育部系统 - 早锻炼获取 | ❌（无从破解微信小程序 QAQ） | +| 计划功能（芒果画饼中） | 支持进度 | +|-------------------|------| +| 教务系统 - 课程表获取 | ✅ | +| 教务系统 - 课程获取 | ⌛️ | +| 教务系统 - 成绩获取 | ⌛️ | +| 教务系统 - 课程表 - 日历订阅 | ⌛️ | +| 体育部系统 - 早锻炼获取 | ❌ | + +| 优化待办 | 支持进度 | +|---------------|------| +| 自定义课程表 CSS 样式 | ⌛️ | +| 生成的静态资源有效期管理 | ⌛️ | ## 运行 diff --git a/src/njupt_suan_api/api/baselib/config.py b/src/njupt_suan_api/api/baselib/config.py index 01003e1..9e523bc 100644 --- a/src/njupt_suan_api/api/baselib/config.py +++ b/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" diff --git a/src/njupt_suan_api/server.py b/src/njupt_suan_api/server.py index ec65a58..fd8917f 100644 --- a/src/njupt_suan_api/server.py +++ b/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") diff --git a/uv.lock b/uv.lock index fb30e0b..98907ac 100644 --- a/uv.lock +++ b/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" },