37 lines
1.6 KiB
Markdown
37 lines
1.6 KiB
Markdown
# API
|
|
|
|
以下是自动生成的 API 文档，包含 NyaHome 的 FastAPI 后端拥有的所有路由端点的有关信息。
|
|
|
|
API 文档会跟随代码仓库主分支的最新状况进行同步。也就是说，此处的 API 文档永远显示最新版本。
|
|
|
|
## 查看 NyaHome Swagger UI 或 ReDoc
|
|
|
|
FastAPI 提供内置的文档功能，位于开发服务器的 `/docs` 和 `/redoc` 两处路径。
|
|
NyaHome 提供关闭它们的选项（并且默认关闭），但如果你有开发需求，打开它们自然是比较方便的。
|
|
|
|
由 FastAPI 打开的文档是由当前代码生成的，可以反应开发中的最新更改，或者查看当前版本的路由信息（如果你没有使用最新版本）。
|
|
|
|
## 导出 openapi.json
|
|
|
|
你可以从一个部署完成的 NyaHome 实例中导出 openapi.json。
|
|
|
|
```bash
|
|
uv run nyahome openapi [path]
|
|
```
|
|
|
|
以上命令会生成 openapi.json 文件。`path` 参数的默认值是 `openapi.json`，意味着 openapi.json 会被保存在执行位置（仓库根目录）。
|
|
|
|
你也可以从一个正在运行的 NyaHome 实例访问 `/openapi.json` 来在线查看 openapi.json，此功能也默认关闭。
|
|
|
|
## 构建文档自动集成
|
|
|
|
`pyproject.toml` 中配置了一个项目任务，来方便将最新的 openapi.json 导出到 `/docs` 路径下的指定位置，从而与 VitePress 进行集成。
|
|
|
|
```bash
|
|
uv run task openapi-docs
|
|
```
|
|
|
|
这会将 openapi.json 保存到 `/docs/.vitepress/theme/openapi.json`。事实上这是对上面的 `nyahome openapi` 命令的封装。
|
|
|
|
此命令一般适合在 CI/CD 流水线中运行比较合适，或者在开发阶段需要预览 API 文档的渲染效果。
|