Skip to main content

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.

​
Documentation Conventions

This page defines the baseline rules for maintaining the NexFi docs site.

​
Response Envelope

All four modules use the same success envelope: 
{
  "code": 0,
  "msg": "ok",
  "data": {}
}
Rules:
  • code = 0 means success.
  • msg = "ok" is the default success message.
  • data contains the business payload.
  • Modules may include extra fields such as traceId, but must not replace the shared code / msg / data structure.

​
Path Placeholder Style

All docs pages and examples should use brace placeholders: 
/api/v1/orders/{id}
/api/v1/balances/{address}
Do not use: 
/api/v1/orders/:id
/api/v1/balances/:address
The reason is simple:
  • OpenAPI uses {param}
  • Mintlify API Reference also uses {param}
  • Keeping MDX pages identical avoids drift

​
MDX vs OpenAPI Responsibilities

Each endpoint is documented in two layers:
  1. MDX guide pages Used for business meaning, integration flow, field explanation, and narrative examples.
  2. OpenAPI files Used for machine-readable contracts, schema rendering, and Mintlify API Reference generation.
Maintenance rule:
  • If endpoint behavior or schema changes, update both MDX and OpenAPI.
  • If only wording or business explanation changes, MDX update may be enough.
  • If API Reference looks too thin, add description and example into OpenAPI first.

​
Bilingual Rules

English and Chinese are maintained as separate source files. Required sync points for every important API change:
  • English MDX page
  • Chinese MDX page
  • English OpenAPI file
  • Chinese OpenAPI file
Do not assume one language can lag behind the other for contract-level changes.

​
Naming Rules

Guide pages:
  • Use concise English filenames in the English tree.
  • Use the same module structure under zh/.
OpenAPI files: 
<module>.openapi.yaml
zh/<module>.openapi.yaml

​
Example Rules

Examples should follow these conventions:
  • Use realistic but clearly non-production IDs and addresses.
  • Keep field names aligned with the current schema.
  • Success examples must use code: 0 and msg: "ok".
  • Status examples should use valid enum values from the current OpenAPI schema.

​
Update Checklist

When adding or changing an endpoint:
  1. Update the module OpenAPI file.
  2. Add or refresh field descriptions.
  3. Add or refresh request and response examples.
  4. Update the English MDX guide page.
  5. Update the Chinese MDX guide page.
  6. Update the Chinese OpenAPI file if localized API Reference wording is expected.
  7. If navigation changes, update docs.json.

​
Validation Checklist

Before considering the docs update complete, verify:
  • path placeholders use {param}
  • success examples use code: 0 and msg: "ok"
  • English and Chinese pages cover the same endpoint set
  • OpenAPI files parse successfully
  • examples do not contradict schema enums or required fields