How to create beautiful API reference documentation with Syntext.
5 min read
This guide shows how to create structured API reference documentation with individual endpoint pages, grouped navigation, and rich parameter documentation.
Structure
Syntext recommends organizing API docs with one file per endpoint:
text
docs/
├── api-reference/
│ ├── overview.mdx # API introduction
│ ├── authentication.mdx # Auth guide
│ ├── projects/
│ │ ├── list.mdx # GET /projects
│ │ ├── get.mdx # GET /projects/{id}
│ │ ├── create.mdx # POST /projects
│ │ ├── update.mdx # PATCH /projects/{id}
│ │ └── delete.mdx # DELETE /projects/{id}
│ ├── builds/
│ │ ├── list.mdx
│ │ ├── get.mdx
│ │ └── trigger.mdx
│ └── search/
│ └── query.mdx
Endpoint Frontmatter
Each endpoint file should include protocol-specific frontmatter:
mdx
---
title: Create Project
protocol: rest
method: POST
endpoint: /v1/projects
description: "Create a new documentation project"
---
REST Endpoints
Field
Required
Description
title
Yes
Page title and sidebar label
protocol
Yes
Set to rest
method
Yes
HTTP method: GET, POST, PUT, PATCH, DELETE
endpoint
Yes
API path (e.g., /v1/projects/{id})
description
No
Brief description for search results
GraphQL Operations
mdx
---
title: Get Session
protocol: graphql
operation: query
name: GetSession
---
WebSocket Events
mdx
---
title: Session Connected
protocol: websocket
event: session.connected
direction: server-to-client
---
Navigation with Sections
Group endpoints under sections in your syntext.json:
json
{
"navigation": [
{
"group": "API Reference",
"pages": [
"api-reference/overview",
"api-reference/authentication"
]
},
{
"group": "Projects",
"pages": [
"api-reference/projects/list",
"api-reference/projects/get",
"api-reference/projects/create",
"api-reference/projects/update",
"api-reference/projects/delete"
]
},
{
"group": "Builds",
"pages": [
"api-reference/builds/list",
"api-reference/builds/get",
"api-reference/builds/trigger"
]
}
]
}
Each group becomes a labelled group in the sidebar, in the order listed.
Endpoint Component
On an endpoint page the method and path bar is drawn from the method and
endpoint frontmatter, so you don't add it yourself. On a guide page, use the
<Endpoint> component to display a method and path:
Document error responses with HTTP status codes and response body examples:
mdx
## Error Responses
### 400 Bad Request
Returned when required fields are missing or have invalid values.
\`\`\`json
{
"error": {
"code": "invalid_request",
"message": "Required field missing or invalid value",
"details": {
"field": "name",
"issue": "Name is required"
}
}
}
\`\`\`
### 404 Not Found
Returned when the resource does not exist.
\`\`\`json
{
"error": {
"code": "not_found",
"message": "Resource does not exist"
}
}
\`\`\`
### 409 Conflict
Returned when a resource with this identifier already exists.
\`\`\`json
{
"error": {
"code": "conflict",
"message": "Resource with this identifier already exists"
}
}
\`\`\`
### 429 Too Many Requests
Returned when the rate limit has been exceeded.
\`\`\`json
{
"error": {
"code": "rate_limited",
"message": "Too many requests. Try again later.",
"retryAfter": 60
}
}
\`\`\`
OpenAPI Import
If you have an OpenAPI spec, the fastest path is build-time generation — list the spec in syntext.json and every deploy regenerates the endpoint pages: