Supported API Formats

Specra's API documentation system supports multiple industry-standard formats, allowing you to use your existing API specifications without conversion.

Quick Overview

How It Works

The API documentation system uses auto-detection by default. Simply reference your spec file and the system automatically determines the format:

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

The parser will detect whether your file is:

• ✅ Specra format (native)
• ✅ OpenAPI 3.x or Swagger 2.0
• ✅ Postman Collection v2.0 or v2.1

Format Comparison

Choosing a Format

Use Specra Format When:

• 📝 Writing docs from scratch
• 🎯 Need a simple, minimal format
• 🚀 Want to get started quickly
• 📖 Documenting < 20 endpoints

Example:

1{
2  "title": "My API",
3  "baseUrl": "https://api.example.com",
4  "endpoints": [...]
5}

View Specra Example →

Use OpenAPI When:

• 🏢 Following enterprise standards
• 🔧 Generating specs from code
• 🔄 Sharing specs across tools
• 📊 Need detailed schema validation
• 🌐 Working with API gateways

Example:

1{
2  "openapi": "3.0.0",
3  "info": {...},
4  "paths": {...}
5}

View OpenAPI Example →

Use Postman When:

• 🧪 Your team uses Postman for testing
• 💾 Have existing Postman collections
• 🔁 Want docs in sync with tests
• 📸 Need saved response examples
• ⚡ Want quick export workflow

Example:

1{
2  "info": {
3    "schema": "https://schema.getpostman.com/..."
4  },
5  "item": [...]
6}

View Postman Example →

Workflow Examples

Workflow 1: Start Simple (Specra)

Perfect for new projects or small APIs:

1. Create a Specra JSON file in /public/api-specs/
2. Add your endpoints with examples
3. Reference in MDX:

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

4. Done! Interactive docs are live

Workflow 2: Use Existing OpenAPI (OpenAPI)

Great if you're already using OpenAPI:

1. Generate OpenAPI spec from your code (e.g., FastAPI, Swagger, etc.)
2. Place in /public/api-specs/
3. Reference in MDX:

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

4. Keep in sync by regenerating when code changes

Workflow 3: Export from Postman (Postman)

Ideal for teams using Postman:

1. Develop and test your API in Postman
2. Add response examples in Postman
3. Export collection (v2.1 format)
4. Place in /public/api-specs/
5. Reference in MDX:

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

6. Re-export when you update your collection

Mixed Approach

You can use multiple formats in the same project:

1<!-- Auto-generated OpenAPI for main API -->
2<ApiReference spec="/api-specs/main-api-openapi.json" />
3 
4<!-- Postman collection for external API -->
5<ApiReference spec="/api-specs/third-party-postman.json" />
6 
7<!-- Specra for internal tools -->
8<ApiReference spec="/api-specs/internal-tools-specra.json" />

Advanced Usage

Explicit Parser Selection

While auto-detection works well, you can explicitly specify the parser:

1<ApiReference spec="/api-specs/my-api.json" parser="openapi" />
2<ApiReference spec="/api-specs/my-api.json" parser="postman" />
3<ApiReference spec="/api-specs/my-api.json" parser="specra" />

Disable Playground

Turn off the interactive playground if you don't need it:

1<ApiReference spec="/api-specs/my-api.json" showPlayground={false} />

Multiple Versions

Document multiple API versions:

1## Version 2.0 (Current)
2 
3<ApiReference spec="/api-specs/api-v2.json" />
4 
5## Version 1.0 (Deprecated)
6 
7<Callout type="warning">
8This version will be sunset on June 1, 2024
9</Callout>
10 
11<ApiReference spec="/api-specs/api-v1.json" showPlayground={false} />

Common Features

Regardless of which format you choose, all specs support:

✅ Path parameters - Dynamic URL segments (:id, {id})

✅ Query parameters - URL query strings

✅ Request headers - Custom headers

✅ Request bodies - JSON payloads

✅ Response examples - Sample responses

✅ Multiple response codes - 200, 404, 500, etc.

✅ Authentication - Bearer, API Key, Basic

✅ Interactive playground - Test APIs live

Next Steps

Ready to start documenting your API? Pick a format and dive in:

• View Specra Format Example →
• View OpenAPI Example →
• View Postman Example →
• Learn About Manual Components →