API Documentation

Create beautiful, interactive API documentation with dedicated components for endpoints, parameters, and responses.

Basic API Endpoint

GET /users
Retrieve a list of all users.
markdown 
<Api method="GET" path="/users">
  Retrieve a list of all users.
</Api>

HTTP Methods

GET /users/{id}
Get a specific user by ID.
POST /users
Create a new user.
PUT /users/{id}
Update an existing user.
PATCH /users/{id}
Partially update a user.
DELETE /users/{id}
Delete a user.

Parameters

Document request parameters with ParamField:

GET /users
page integer query optional
Page number for pagination.
limit integer query optional
Default: 20
Number of results per page.
search string query optional
Filter users by name or email.
markdown 
<Api method="GET" path="/users">
  <ParamField name="page" type="integer" paramType="query">
    Page number for pagination.
  </ParamField>
  <ParamField name="limit" type="integer" paramType="query" default="20">
    Number of results per page.
  </ParamField>
  <ParamField name="search" type="string" paramType="query">
    Filter users by name or email.
  </ParamField>
</Api>

Parameter Types

POST /users/{id}/avatar
id string path required
The unique user identifier.
Authorization string header required
Bearer token for authentication.
file binary body required
The avatar image file.

Response Fields

Document response structure with ResponseField:

GET /users/{id}
id string path required
User ID
id string
Unique user identifier.
email string
User's email address.
name string
User's display name.
created_at string
ISO 8601 timestamp of account creation.
avatar_url string nullable
URL to user's avatar image, if set.
markdown 
<Api method="GET" path="/users/{id}">
  <ResponseField name="id" type="string">
    Unique user identifier.
  </ResponseField>
  <ResponseField name="email" type="string">
    User's email address.
  </ResponseField>
  <ResponseField name="avatar_url" type="string" nullable>
    URL to user's avatar image, if set.
  </ResponseField>
</Api>

Complete API Example

POST /users 🔒 Bearer Token
Create User
Creates a new user account in the system.
Authorization string header required
Bearer token: `Bearer your-api-key`
email string body required
User's email address. Must be unique.
name string body required
User's display name (2-50 characters).
password string body required
Password (minimum 8 characters).
role string body optional
Default: user
User role: `admin`, `editor`, or `user`.
id string
Unique identifier for the created user.
email string
The user's email address.
name string
The user's display name.
role string
The assigned user role.
created_at string
ISO 8601 creation timestamp.

Generic Fields

Use Field for general-purpose field documentation:

pagination object optional
All list endpoints return pagination metadata.
pagination.page integer optional
Current page number (1-indexed).
pagination.total_pages integer optional
Total number of pages available.
pagination.total_items integer optional
Total number of items across all pages.
markdown 
<Field name="pagination" type="object">
  All list endpoints return pagination metadata.
</Field>

<Field name="pagination.page" type="integer">
  Current page number (1-indexed).
</Field>

OpenAPI Import

Generate API documentation automatically from OpenAPI/Swagger specs:

bash 
stardust openapi openapi.yaml -o docs/api

This creates markdown files for each endpoint with:

  • Method and path
  • Description from spec
  • All parameters with types
  • Response schemas
  • Authentication requirements

See the OpenAPI CLI Reference for more options.

Attributes Reference

Api

Attribute Type Default Description
method string "GET" HTTP method
path string "/" API endpoint path
title string - Optional endpoint title
auth string - Authentication requirement

ParamField

Attribute Type Default Description
name string required Parameter name
type string "string" Data type
paramType string "query" Location: query, path, header, body
required boolean false Whether required
default string - Default value

ResponseField

Attribute Type Default Description
name string required Field name
type string "any" Data type
nullable boolean false Whether can be null

Field

Attribute Type Default Description
name string required Field name
type string "any" Data type
required boolean false Whether required
default string - Default value
deprecated boolean false Mark as deprecated

Best Practices

Info

  • Group related endpoints together on the same page
  • Always document required vs optional parameters
  • Include example values in descriptions
  • Document error responses and status codes
  • Use consistent naming conventions
Edit this page on GitHub