跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.nexfi.robert.dpdns.org/llms.txt

Use this file to discover all available pages before exploring further.

​
文档规范

本页定义 NexFi 文档站后续维护时必须遵守的基线规则。

​
统一响应包

四个模块统一使用同一套成功响应格式： 
{
  "code": 0,
  "msg": "ok",
  "data": {}
}
规则：
  • code = 0 表示成功。
  • msg = "ok" 作为默认成功消息。
  • data 承载业务数据。
  • 模块可以增加 traceId 等额外字段，但不能替换 code / msg / data 这套基础结构。

​
路径占位符规范

所有文档页和示例统一使用花括号占位： 
/api/v1/orders/{id}
/api/v1/balances/{address}
不要再使用： 
/api/v1/orders/:id
/api/v1/balances/:address
原因：
  • OpenAPI 使用 {param}
  • Mintlify API Reference 也使用 {param}
  • MDX 与 OpenAPI 保持一致可以避免漂移

​
MDX 与 OpenAPI 的职责分工

每个接口分两层维护：
  1. MDX 说明页 用来写业务语义、接入流程、字段解释和叙述式示例。
  2. OpenAPI 文件 用来描述机器可读接口契约、schema 和 Mintlify API Reference。
维护规则：
  • 接口行为或字段结构变化时，MDX 和 OpenAPI 都要改。
  • 只有说明性文字变化时，可以只改 MDX。
  • 如果 API Reference 显示太薄，优先补 OpenAPI 的 description 和 example。

​
双语维护规则

英文和中文是两套独立源文件，不是自动翻译关系。 每次重要接口变更，至少同步检查：
  • 英文 MDX 页面
  • 中文 MDX 页面
  • 英文 OpenAPI 文件
  • 中文 OpenAPI 文件
不要默认允许一种语言长期落后于另一种语言。

​
命名规则

说明页：
  • 英文树使用简洁英文文件名
  • 中文树在 zh/ 下保持相同模块结构
OpenAPI 文件： 
<module>.openapi.yaml
zh/<module>.openapi.yaml

​
示例规则

示例数据遵守以下要求：
  • 使用真实风格但非生产环境的 ID、地址和哈希
  • 字段名必须与当前 schema 一致
  • 成功示例必须使用 code: 0 和 msg: "ok"
  • 状态示例必须来自当前 OpenAPI 枚举值

​
变更检查清单

新增或修改接口时，按以下顺序执行：
  1. 更新模块 OpenAPI 文件
  2. 补充或更新字段说明
  3. 补充或更新请求、响应示例
  4. 更新英文 MDX 页面
  5. 更新中文 MDX 页面
  6. 如需要中文 API Reference 正常展示，再同步更新中文 OpenAPI
  7. 若导航变化，再更新 docs.json

​
验收检查清单

提交前至少确认：
  • 路径占位符统一使用 {param}
  • 成功示例统一使用 code: 0 和 msg: "ok"
  • 中英文页面覆盖相同接口范围
  • OpenAPI 文件可以正常解析
  • 示例与 schema 的枚举、必填字段没有冲突