Use the systematic template for comprehensive documentation of complex APIs with multiple endpoints, or choose the narrative template for simpler APIs where you want engaging, user-focused documentation.
Template 1 — Systematic API Documentation Generator
Best for: Use this when documenting complex APIs with multiple endpoints, requiring comprehensive coverage of all technical details and edge cases.
**API Overview**: Brief description and primary use cases
**Authentication**: [Auth Method, e.g., API Key, OAuth 2.0, Bearer Token]
**Base URL**: [Base URL, e.g., https://api.example.com/v1, https://payment.myapp.com/api]
**Endpoints**: Document these endpoints: [Endpoint List, e.g., GET /users, POST /payments, DELETE /sessions]
For each endpoint, include:
– HTTP method and URL
– Required/optional parameters with data types
– Request body examples (JSON format)
– Response examples (success and error cases)
– Status codes and their meanings
– Rate limiting information
**Error Handling**: Standard error response format
**Code Examples**: Include examples in [Programming Languages, e.g., Python, JavaScript, cURL]
**Additional Notes**: [Special Requirements, e.g., webhook setup, pagination, versioning]
Target audience: [Developer Level, e.g., intermediate developers, frontend teams, mobile developers]. Use clear, concise language with practical examples.
• Produces consistent formatting and structure across all API endpoints, making it easier for developers to navigate
• Automatically includes essential technical details like status codes, rate limits, and data types that are often forgotten
• Creates ready-to-use code examples in multiple programming languages, reducing developer onboarding time
## Overview
Secure payment processing API for e-commerce applications with support for credit cards and digital wallets.
## Authentication
API Key authentication via `X-API-Key` header.
## Base URL
`https://api.payments.example.com/v1`
### POST /charges
Create a new payment charge.
**Parameters:**
– `amount` (integer, required): Amount in cents
– `currency` (string, required): ISO currency code
– `source` (string, required): Payment source token
**Example Request:**
“`json
{
“amount”: 2000,
“currency”: “usd”,
“source”: “tok_visa_4242”
}
“`
**Response (200):**
“`json
{
“id”: “ch_1234567890”,
“status”: “succeeded”,
“amount”: 2000
}
“`
• List your most important endpoints first in the endpoint list – AI tends to provide more detailed examples for items mentioned earlier
Template 2 — Developer-Focused API Story Generator
Best for: Use this when you want engaging, narrative-style documentation that walks developers through real-world use cases and implementation scenarios.
**The Developer Journey:**
1. **Quick Start**: What can developers build with this API? Start with an exciting use case for [Primary Use Case, e.g., building dashboards, creating mobile apps, automating workflows].
2. **Getting Your First Response**: Walk through authentication with [Auth Method, e.g., API key registration, OAuth flow] and show a simple first API call to [Key Endpoint, e.g., /data/current, /users/profile, /metrics/overview].
3. **Building Something Real**: Demonstrate a practical implementation scenario: [Real-World Scenario, e.g., creating a weather widget, analyzing user engagement, processing customer data]. Include code examples in [Preferred Language, e.g., Python, JavaScript, PHP].
4. **Advanced Features**: Cover [Advanced Features, e.g., webhooks, batch processing, custom filters] with examples of when and how to use them.
5. **Troubleshooting**: Address common issues developers face, especially around [Common Pain Points, e.g., rate limiting, data formatting, authentication errors].
Write in a conversational but professional tone. Include plenty of code examples and explain the ‘why’ behind API design decisions.
• Focuses on practical implementation scenarios rather than dry technical specifications, improving developer adoption
• Naturally incorporates troubleshooting and best practices within the narrative flow, reducing support tickets
• Generates documentation that showcases the API’s value proposition through real-world use cases
## What You Can Build
Imagine creating a smart agriculture app that helps farmers optimize irrigation based on hyperlocal weather predictions. The Weather Insights API makes this possible with real-time data and 7-day forecasts.
## Your First API Call
Grab your API key from the dashboard and let’s get current conditions:
“`python
import requests
response = requests.get(
‘https://api.weather-insights.com/v1/current’,
headers={‘API-Key’: ‘your_key_here’},
params={‘lat’: 40.7128, ‘lon’: -74.0060}
)
weather = response.json()
print(f”Temperature: {weather[‘temperature’]}°F”)
“`
## Building a Smart Irrigation System
Now let’s create something practical. Here’s how to build a system that suggests irrigation timing…
• Mention 2-3 common pain points in your prompt to ensure the AI addresses real developer challenges rather than generic troubleshooting