API Documentation

Specra provides a powerful yet flexible system for documenting REST APIs. Whether you have 5 endpoints or 500, we've got you covered.

Two Approaches

1. Auto-Generated Documentation

Perfect for large APIs or when you already have specs.

Simply create or export your spec file and reference it:

1<ApiReference spec="/api-specs/my-api.json" />

The system auto-detects the format and generates beautiful, interactive documentation.

Examples:

• Specra Format (JSONPlaceholder) →
• OpenAPI 3.0 Format →
• Postman Collection →

Learn More About Formats →

2. Manual MDX Components

Perfect for small APIs or when you need custom layouts.

Use individual components to craft your documentation:

1<ApiEndpoint
2  method="GET"
3  path="/api/users/:id"
4  summary="Get user by ID"
5>
6  <ApiParams params={[...]} />
7  <ApiResponse status={200} example={{...}} />
8  <ApiPlayground method="GET" path="/api/users/123" />
9</ApiEndpoint>

Example:

• Manual Component Example →

Quick Start

Auto-Generated (Recommended)

1. Create your spec file (Specra, OpenAPI, or Postman)
2. Place it in /public/api-specs/my-api.json
3. Add to your MDX:

1---
2title: API Reference
3---
4 
5# My API Documentation
6 
7<ApiReference spec="/api-specs/my-api.json" />

That's it! You now have:

• ✅ Auto-generated endpoint documentation
• ✅ Interactive API playground
• ✅ Collapsible accordion UI
• ✅ Syntax-highlighted examples
• ✅ Request/response schemas

Manual Components

1. Create an MDX file in docs/
2. Use API components:

1---
2title: API Reference
3---
4 
5# My API
6 
7<ApiEndpoint method="GET" path="/users" summary="List users">
8  <ApiParams
9    title="Query Parameters"
10    params={[
11      { name: "page", type: "number", description: "Page number" }
12    ]}
13  />
14 
15  <ApiResponse
16    status={200}
17    description="Success"
18    example={[{ id: 1, name: "John" }]}
19  />
20 
21  <ApiPlayground
22    method="GET"
23    path="/users"
24    baseUrl="https://api.example.com"
25  />
26</ApiEndpoint>

Available Components

<ApiReference>

Auto-generate docs from spec files.

1<ApiReference
2  spec="/api-specs/my-api.json"  // Path to spec file
3  parser="auto"                   // auto | specra | openapi | postman
4  showPlayground={true}           // Show interactive playground
5/>

<ApiEndpoint>

Document a single endpoint (accordion-style).

1<ApiEndpoint
2  method="GET"              // GET | POST | PUT | PATCH | DELETE
3  path="/api/users/:id"     // API path
4  summary="Get user by ID"  // Short description
5  defaultOpen={false}       // Start expanded?
6>
7  {/* Child components */}
8</ApiEndpoint>

<ApiParams>

Display parameters (path, query, body).

1<ApiParams
2  title="Path Parameters"
3  params={[
4    {
5      name: "id",
6      type: "string",
7      required: true,
8      description: "User ID",
9      example: "user_123"
10    }
11  ]}
12/>

<ApiResponse>

Show response examples.

1<ApiResponse
2  status={200}
3  description="User found"
4  example={{
5    id: "user_123",
6    name: "John Doe",
7    email: "john@example.com"
8  }}
9/>

<ApiPlayground>

Interactive API testing.

1<ApiPlayground
2  method="GET"
3  path="/users/:id"
4  baseUrl="https://api.example.com"
5  headers={{ "Authorization": "Bearer ..." }}
6  pathParams={[
7    { name: "id", type: "string", example: "user_123" }
8  ]}
9  defaultBody='{"key": "value"}'
10/>

Features

Interactive Playground

Every endpoint includes a built-in playground where users can:

• ✅ Edit path parameters
• ✅ Modify request headers
• ✅ Update request body
• ✅ Send real API requests
• ✅ View formatted responses

Accordion UI

Endpoints are collapsible by default, making it easy to:

• Browse many endpoints quickly
• Expand only what you need
• Keep the page clean and organized

Syntax Highlighting

All code examples include:

• JSON syntax highlighting
• Line numbers
• Copy button
• Dark mode support

Authentication

Document your auth requirements:

• Bearer tokens
• API keys
• Basic auth
• Custom headers

Format Support

Compare Formats →

Examples

Complete API (Auto-Generated)

Using JSONPlaceholder as a real working example:

View Live Example →

OpenAPI Specification

Enterprise-grade API documentation:

View OpenAPI Example →

Postman Collection

Exported directly from Postman:

View Postman Example →

Manual Components

Hand-crafted for custom needs:

View Manual Example →

Best Practices

1. Choose the Right Approach

Use auto-generated when:

• You have > 10 endpoints
• You already have a spec file
• You want consistency
• You need code generation

Use manual components when:

• You have < 10 endpoints
• You need custom layouts
• You want full control
• You're documenting gradually

2. Provide Examples

Always include realistic examples:

• Request bodies with actual data
• Response examples that match reality
• Edge cases and errors
• Authentication examples

3. Keep It Updated

For auto-generated docs:

• Regenerate specs when code changes
• Re-export Postman collections regularly
• Version your spec files

For manual docs:

• Review when API changes
• Test playground regularly
• Update examples

4. Organize by Feature

Group related endpoints:

1## User Management
2 
3<ApiReference spec="/api-specs/users.json" />
4 
5## Product Catalog
6 
7<ApiReference spec="/api-specs/products.json" />
8 
9## Orders
10 
11<ApiReference spec="/api-specs/orders.json" />

5. Add Context

Enhance with explanatory text:

1## Authentication
2 
3All endpoints require a valid JWT token.
4 
5<Callout type="info">
6Get your API key from the [developer dashboard](https://example.com/dashboard).
7</Callout>
8 
9<ApiReference spec="/api-specs/my-api.json" />

Next Steps

Ready to document your API?

1. Choose your format - Compare formats →
2. See examples - View examples →
3. Start building - Create your first spec file
4. Go live - Deploy your documentation

Resources

• Supported Formats Guide
• Specra Format Example
• OpenAPI Example
• Postman Example
• Manual Components Example
• Parser Technical Docs