# 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 文档的渲染效果。