API Reference

SuperDocs provides specialized components for documenting REST APIs. This page demonstrates how to use them to create beautiful, interactive API documentation.

APIEndpoint

Display an API endpoint with method badges, authentication indicators, and descriptions.

<APIEndpoint
  method="GET"
  path="/users/{id}"
  description="Retrieve a user by their unique ID."
  auth="bearer"
  baseUrl="https://api.example.com"
/>

GET /users/{id}

Bearer

Retrieve a user by their unique ID.

Supported Methods

GET /users

List all users

POST /users

Bearer

Create a new user

PUT /users/{id}

Bearer

Update a user

PATCH /users/{id}

API Key

Partially update a user

DELETE /users/{id}

Bearer

Delete a user

Deprecated Endpoint

<APIEndpoint method="GET" path="/v1/users" description="Old endpoint" deprecated />

GET /v1/users

Deprecated

This endpoint is deprecated. Use /users instead.

Prop	Type	Description
`method`	`string`	HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `HEAD`
`path`	`string`	The API path with placeholders like `{id}`
`description`	`string`	Brief description of the endpoint
`deprecated`	`boolean`	Mark endpoint as deprecated
`auth`	`string`	Authentication type: `bearer`, `api-key`, `basic`, or `none`
`baseUrl`	`string`	Base URL for the API

ParamTable & Param

Document request parameters in a structured table with type-colored badges and icons.

<ParamTable type="path">
  <Param name="id" type="string" required>
    The unique identifier of the user.
  </Param>
</ParamTable>

<ParamTable type="query" expandable>
  <Param name="limit" type="integer" default="10">
    Maximum number of results to return.
  </Param>
  <Param name="offset" type="integer" default="0">
    Number of results to skip.
  </Param>
  <Param name="status" type="string" enum={["active", "pending", "inactive"]}>
    Filter by user status.
  </Param>
</ParamTable>

Path Parameters

id required

string

The unique identifier of the user.

Query Parameters

limit

integer = 10

Maximum number of results to return.

offset

integer = 0

Number of results to skip.

status

string

Filter by user status.

Allowed values:

activependinginactive

Parameter Types

Header Parameters

Authorization required

string

Bearer token for authentication.

X-Request-ID

string

Optional request tracking ID.

Body Parameters

email required

string

User’s email address.

role deprecated

string

User role (deprecated, use permissions instead).

Allowed values:

adminuserguest

Component	Prop	Type	Description
`ParamTable`	`title`	`string`	Section title (auto-generated from type)
`ParamTable`	`type`	`string`	Parameter type: `path`, `query`, `header`, `body`, `cookie`
`ParamTable`	`expandable`	`boolean`	Make the section collapsible
`ParamTable`	`defaultOpen`	`boolean`	Default state for expandable (default: true)
`Param`	`name`	`string`	Parameter name
`Param`	`type`	`string`	Data type (string, integer, boolean, array, object, etc.)
`Param`	`required`	`boolean`	Whether the parameter is required
`Param`	`default`	`string`	Default value
`Param`	`deprecated`	`boolean`	Mark as deprecated
`Param`	`enum`	`string[]`	List of allowed values

ResponseField

Document API response fields with support for nested structures.

Simple Fields

<ResponseField name="id" type="string">
  The user's unique identifier.
</ResponseField>
<ResponseField name="email" type="string" required>
  The user's email address.
</ResponseField>
<ResponseField name="name" type="string" nullable>
  The user's display name (may be null).
</ResponseField>
<ResponseField name="created_at" type="datetime">
  ISO 8601 timestamp of when the user was created.
</ResponseField>

id string

The user’s unique identifier.

email string

The user’s email address.

name string nullable

The user’s display name (may be null).

created_at datetime

ISO 8601 timestamp of when the user was created.

Nested Fields (Expandable)

<ResponseField name="data" type="object" expandable>
  <ResponseField name="user" type="object" expandable>
    <ResponseField name="id" type="string">User ID</ResponseField>
    <ResponseField name="email" type="string">Email address</ResponseField>
  </ResponseField>
  <ResponseField name="permissions" type="array">
    List of user permissions.
  </ResponseField>
</ResponseField>

data object

user object

id string

User ID

email string

Email address

profile object

avatar string nullable

Profile picture URL

bio string nullable

User biography

permissions array

List of user permissions.

Prop	Type	Description
`name`	`string`	Field name
`type`	`string`	Data type (color-coded)
`nullable`	`boolean`	Whether the field can be null
`required`	`boolean`	Mark as required field
`deprecated`	`boolean`	Mark as deprecated
`expandable`	`boolean`	Make collapsible for nested content
`defaultOpen`	`boolean`	Default state for expandable (default: true)

APIPlayground

Interactive API testing component that lets users make real API requests. Features include:

Authentication support - Bearer tokens, API keys, and Basic auth
Code generation - Generate code snippets in cURL, JavaScript, Python, and Go
Request builder - Add parameters, headers, and request bodies
Response viewer - See response body and headers with syntax highlighting

<APIPlayground
  method="GET"
  path="/users"
  baseUrl="https://jsonplaceholder.typicode.com"
  auth="bearer"
  defaultHeaders={{ "Content-Type": "application/json" }}
/>

GET /users

With Authentication

POST /posts

Authorization

Bearer Token

Prop	Type	Description
`method`	`string`	HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
`path`	`string`	API endpoint path
`baseUrl`	`string`	Base URL for the API (editable by users)
`auth`	`string`	Auth type: `bearer`, `api-key`, `basic`, or `none`
`defaultHeaders`	`object`	Default headers to include

Tip

The APIPlayground allows users to add custom headers, query parameters, and request bodies. Switch to the “Code” tab to get ready-to-use snippets!

OpenAPI Support

SuperDocs can automatically generate API documentation from OpenAPI/Swagger specifications.

OpenAPISpec Component

Renders all endpoints from an OpenAPI spec file:

import { parseOpenAPIFile } from 'superdocs-theme-default/utils/openapi';

// In your .astro file frontmatter:
const spec = await parseOpenAPIFile('./api-spec.yaml');

// In your template:
<OpenAPISpec spec={spec} showPlayground />

OpenAPIEndpoint Component

Render a single endpoint from a spec:

<OpenAPIEndpoint spec={spec} method="GET" path="/users/{id}" showPlayground />

Component	Prop	Type	Description
`OpenAPISpec`	`spec`	`object`	Parsed OpenAPI spec
`OpenAPISpec`	`tag`	`string`	Filter endpoints by tag
`OpenAPISpec`	`showPlayground`	`boolean`	Show interactive playground
`OpenAPISpec`	`baseUrl`	`string`	Override base URL
`OpenAPIEndpoint`	`spec`	`object`	Parsed OpenAPI spec
`OpenAPIEndpoint`	`method`	`string`	HTTP method
`OpenAPIEndpoint`	`path`	`string`	Endpoint path

Complete API Documentation Example

Here’s a full example of documenting an API endpoint with all features:

Get User by ID

GET /users/{id}

Bearer

Retrieve detailed information about a specific user.

Path Parameters

id required

string

The unique identifier of the user (UUID format).

Query Parameters

include

string

Related resources to include in the response.

Allowed values:

postscommentsprofile

fields

string

Comma-separated list of fields to return.

Response

{
  "id": "usr_abc123",
  "email": "john@example.com",
  "name": "John Doe",
  "avatar_url": "https://example.com/avatar.jpg",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-06-20T14:45:00Z"
}

data object

id string

Unique user identifier with usr_ prefix.

email string

User’s verified email address.

name string nullable

User’s display name.

avatar_url string nullable

URL to the user’s profile picture.

metadata object

created_at datetime

When the user account was created.

updated_at datetime

When the user was last modified.

Try It

GET /users/1

Authorization

Bearer Token

Create User

POST /users

Bearer

Create a new user account.

Body Parameters

email required

string

A valid email address. Must be unique.

password required

string

Password (minimum 8 characters).

name

string

Optional display name.

role

string = user

User role assignment.

Allowed values:

adminuserguest

Example Request

curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"email": "john@example.com", "password": "securepass123", "name": "John Doe"}'

Try It

POST /posts

Authorization

Bearer Token

Delete User

DELETE /users/{id}

Bearer

Permanently delete a user account.

Irreversible Action

Deleting a user will permanently remove all associated data including posts, comments, and files. This action cannot be undone.

Path Parameters

id required

string

The unique identifier of the user to delete.

Response

Returns 204 No Content on success.