Basic ResponseField

Document a simple field:

user_id
string

Unique identifier for the user

<ResponseField field_name="user_id" type="string">

  Unique identifier for the user

</ResponseField>

Required Fields

Mark fields as required:

email
string
required

User's email address (must be unique)

<ResponseField field_name="email" type="string" required={true}>

  User's email address (must be unique)

</ResponseField>

Fields with Default Values

Show default values:

role
string

User's role in the system

<ResponseField field_name="role" type="string" default="user">

  User's role in the system

</ResponseField>

Deprecated Fields

Mark deprecated fields:

legacy_id
number

Old identifier format (use user_id instead)

<ResponseField field_name="legacy_id" type="number" deprecated={true}>

  Old identifier format (use `user_id` instead)

</ResponseField>

Complete API Response

Document an entire API response:

User Object

id
string
required

Unique user identifier in UUID format

email
string
required

User's email address (must be unique across all users)

name
string
required

User's full name

role
string

User role: user, admin, or moderator

avatar_url
string

URL to the user's profile image (optional)

created_at
string
required

ISO 8601 timestamp of when the user was created

updated_at
string
required

ISO 8601 timestamp of last update

email_verified
boolean

Whether the user's email has been verified

<ResponseField field_name="id" type="string" required={true}>

  Unique user identifier in UUID format

</ResponseField>



<ResponseField field_name="email" type="string" required={true}>

  User's email address (must be unique across all users)

</ResponseField>



<ResponseField field_name="name" type="string" required={true}>

  User's full name

</ResponseField>



<ResponseField field_name="role" type="string" default="user">

  User role: `user`, `admin`, or `moderator`

</ResponseField>

Request Parameters

Document API request parameters:

Create User Request

email
string
required

User's email address (must be valid and unique)

password
string
required

Password (minimum 8 characters, must include uppercase, lowercase, and number)

name
string
required

User's full name (2-100 characters)

role
string

User role (defaults to user if not specified)

metadata
object

Optional metadata object with custom key-value pairs

Complex Types

Document nested objects and arrays:

Order Response

id
string
required

Unique order identifier

items
array
required

Array of order items. Each item contains:

  • product_id (string): Product identifier

  • quantity (number): Number of items

  • price (number): Price per item

total
number
required

Total order amount in cents

shipping_address
object
required

Shipping address object with:

  • street (string): Street address

  • city (string): City name

  • state (string): State/province code

  • zip (string): Postal code

  • country (string): Country code (ISO 3166-1 alpha-2)

status
string
required

Order status: pending, processing, shipped, delivered, or cancelled

Data Types

Common data types to use:

Primitives

  • string

  • number

  • boolean

  • null

Complex

  • object

  • array

  • any

Specific

  • UUID

  • ISO8601

  • URL

  • Email

Available Options

field_name
string
required

The name of the field or parameter

type
string
required

Data type (e.g., "string", "number", "boolean", "object", "array")

required
boolean

Whether the field is required

default
string

Default value if not provided

deprecated
boolean

Whether the field is deprecated

Best Practices

Be specific with types

Use specific types when possible:

  • Instead of string, use UUID, Email, URL, or ISO8601

  • Instead of number, specify integer or float

  • For enums, list the possible values

Include validation details

Document validation rules in the description:

  • Minimum/maximum lengths

  • Format requirements

  • Allowed values

  • Pattern constraints

Group related fields

Use headings to group related fields:

### User Fields

<ResponseField ...>



### Metadata Fields

<ResponseField ...>

Document nested structures

For complex objects, either:

  1. Describe nested fields inline in the description

  2. Create a separate section with its own ResponseFields

  3. Link to a detailed schema definition

Common Patterns

Pagination Response

data
array
required

Array of result objects

page
number
required

Current page number (1-indexed)

per_page
number
required

Number of items per page

total
number
required

Total number of items across all pages

total_pages
number
required

Total number of pages

has_next
boolean
required

Whether there is a next page available

has_prev
boolean
required

Whether there is a previous page available

Error Response

error
object
required

Error object containing details about the failure

error.code
string
required

Machine-readable error code (e.g., INVALID_INPUT, NOT_FOUND)

error.message
string
required

Human-readable error message

error.details
array

Array of detailed error objects for validation failures

error.request_id
string
required

Unique request identifier for debugging

ResponseField components are perfect for API documentation. Combine them with code examples showing actual request/response JSON.

Full Image