126 lines
3.8 KiB
YAML
126 lines
3.8 KiB
YAML
# <!-- Powered by BMAD™ Core -->
|
|
---
|
|
template:
|
|
id: api-reference
|
|
name: API Reference Documentation
|
|
version: 1.0
|
|
description: Comprehensive API/function reference documentation with parameters, return values, and examples
|
|
output:
|
|
format: markdown
|
|
filename: "{{api_name}}-reference.md"
|
|
|
|
workflow:
|
|
elicitation: true
|
|
allow_skip: false
|
|
sections:
|
|
- id: overview
|
|
title: API Overview
|
|
instruction: |
|
|
Provide high-level API information:
|
|
- Module, class, or function name
|
|
- Full signature (function signature, class definition, etc.)
|
|
- Import path or package location
|
|
- Version introduced (if applicable)
|
|
- Deprecation status (if applicable)
|
|
elicit: true
|
|
- id: purpose
|
|
title: Purpose and Description
|
|
instruction: |
|
|
Explain what this API does:
|
|
- Primary purpose in 1-2 sentences
|
|
- Use cases where this API is appropriate
|
|
- When NOT to use this API
|
|
- Related APIs that might be alternatives
|
|
elicit: true
|
|
- id: parameters
|
|
title: Parameters
|
|
instruction: |
|
|
Document all parameters in a table format:
|
|
|
|
| Parameter | Type | Required | Default | Description |
|
|
|-----------|------|----------|---------|-------------|
|
|
| name | string | Yes | - | The user's full name |
|
|
| age | int | No | 0 | User's age in years |
|
|
|
|
For each parameter:
|
|
- Name exactly as it appears in code
|
|
- Type (string, int, bool, object, array, etc.)
|
|
- Required or Optional
|
|
- Default value if optional
|
|
- Clear description of what it does
|
|
- Valid ranges or constraints (if applicable)
|
|
- Examples of valid values
|
|
- id: return_value
|
|
title: Return Value
|
|
instruction: |
|
|
Document what the API returns:
|
|
- Return type (including null/None if possible)
|
|
- Description of the returned value
|
|
- Structure of return object (if complex)
|
|
- Return value examples
|
|
- Conditions affecting return value
|
|
- id: exceptions
|
|
title: Exceptions and Errors
|
|
instruction: |
|
|
List possible errors and exceptions:
|
|
|
|
| Exception/Error | Condition | How to Handle |
|
|
|----------------|-----------|---------------|
|
|
| ValueError | Invalid input format | Validate input before calling |
|
|
| FileNotFoundError | File path doesn't exist | Check file exists first |
|
|
|
|
For each exception:
|
|
- Exception name or error code
|
|
- What triggers this exception
|
|
- How to prevent or handle it
|
|
- id: usage_examples
|
|
title: Usage Examples
|
|
instruction: |
|
|
Provide 2-3 realistic code examples:
|
|
|
|
**Example 1: Basic usage**
|
|
```python
|
|
# Show the simplest, most common use case
|
|
result = api_function(required_param="value")
|
|
print(result)
|
|
```
|
|
|
|
**Example 2: Advanced usage**
|
|
```python
|
|
# Show more complex scenario with optional parameters
|
|
result = api_function(
|
|
required_param="value",
|
|
optional_param=42,
|
|
flags={"debug": True}
|
|
)
|
|
```
|
|
|
|
**Example 3: Error handling**
|
|
```python
|
|
# Show proper error handling
|
|
try:
|
|
result = api_function(param="value")
|
|
except ValueError as e:
|
|
print(f"Invalid input: {e}")
|
|
```
|
|
elicit: true
|
|
- id: notes
|
|
title: Notes and Warnings
|
|
instruction: |
|
|
Include important considerations:
|
|
- Performance implications
|
|
- Thread safety
|
|
- Platform-specific behavior
|
|
- Common pitfalls
|
|
- Best practices
|
|
- Security considerations
|
|
- id: related
|
|
title: Related Functions and References
|
|
instruction: |
|
|
Link to related APIs:
|
|
- Similar functions that work together
|
|
- Alternative approaches
|
|
- Required setup functions
|
|
- Functions that use this API's output
|
|
- Relevant documentation sections
|