mirror of
https://github.com/nagisa77/OpenIsle.git
synced 2026-02-22 22:21:09 +08:00
41 lines
1.2 KiB
Markdown
41 lines
1.2 KiB
Markdown
# Docs 协作指引
|
||
|
||
## 1) 适用范围
|
||
|
||
- 作用于 `docs/` 目录及其子目录。
|
||
- 文档需服务“开发者真实使用”，优先准确性与可执行性。
|
||
|
||
## 2) 文档架构
|
||
|
||
- 内容目录：`content/docs/`
|
||
- 生成脚本：`scripts/generate-docs.ts`
|
||
- OpenAPI 输入配置：`lib/openapi.ts`
|
||
- 前端框架：Fumadocs + Next.js（Bun 工具链）
|
||
|
||
## 3) 编辑规则
|
||
|
||
- 优先修正“与代码不一致”的文档，不复制过时描述。
|
||
- 涉及技术栈说明时，以当前代码为准（例如后端为 JPA/Repository）。
|
||
- OpenAPI 自动生成目录（`content/docs/openapi/(generated)`）不要手工细改，改源头配置与脚本。
|
||
- 结构性改动优先维持导航稳定（`meta.json` 与已有 slug）。
|
||
|
||
## 4) OpenAPI 同步规则
|
||
|
||
- 后端 API 变更后，应重新生成文档页面：
|
||
- `bun run generate`
|
||
- 若接口来源地址或文档聚合策略变化，更新：
|
||
- `lib/openapi.ts`
|
||
- `scripts/generate-docs.ts`
|
||
|
||
## 5) 验证命令
|
||
|
||
- 安装依赖：`bun install`
|
||
- 生成 API 文档：`bun run generate`
|
||
- 构建校验：`bun run build`
|
||
- 本地预览：`bun dev`
|
||
|
||
## 6) 输出要求
|
||
|
||
- 说明更新了哪些文档入口（backend/frontend/openapi）。
|
||
- 说明是否需要后端先部署后再刷新文档产物。
|