146 lines
3.4 KiB
Markdown
146 lines
3.4 KiB
Markdown
---
|
|
name: write-api
|
|
description: Start writing API reference documentation for an endpoint
|
|
argument-hint: "[endpoint]"
|
|
arguments:
|
|
- name: endpoint
|
|
description: The API endpoint to document (e.g., POST /accounts)
|
|
required: true
|
|
---
|
|
|
|
# Write API Reference Command
|
|
|
|
You're starting API reference documentation. Follow these steps:
|
|
|
|
## 1. Understand the Endpoint
|
|
|
|
**Endpoint to document:** $ARGUMENTS.endpoint
|
|
|
|
Gather information about:
|
|
- HTTP method and path
|
|
- Path parameters
|
|
- Query parameters
|
|
- Request body schema
|
|
- Response schema
|
|
- Error conditions
|
|
|
|
## 2. Required Sections
|
|
|
|
Every endpoint must include:
|
|
|
|
### HTTP Method and Path
|
|
```markdown
|
|
`POST /v1/organizations/{organizationId}/ledgers/{ledgerId}/accounts`
|
|
```
|
|
|
|
### Path Parameters
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
|
|
### Query Parameters (if applicable)
|
|
| Parameter | Type | Default | Description |
|
|
|-----------|------|---------|-------------|
|
|
|
|
### Request Body
|
|
```json
|
|
{
|
|
"field": "value"
|
|
}
|
|
```
|
|
|
|
### Request Body Fields
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
|
|
### Response
|
|
```json
|
|
{
|
|
"field": "value"
|
|
}
|
|
```
|
|
|
|
### Response Fields
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
|
|
### Errors
|
|
| Status Code | Error Code | Description |
|
|
|-------------|------------|-------------|
|
|
|
|
## 3. Field Description Patterns
|
|
|
|
**UUID:** "The unique identifier of the [Entity]"
|
|
|
|
**String with constraints:** "[Purpose] (max N chars, format)"
|
|
|
|
**Enum:** "[Purpose]: `value1`, `value2`, `value3`"
|
|
|
|
**Boolean:** "If `true`, [behavior]. Default: `value`"
|
|
|
|
**Timestamp:** "Timestamp of [event] (UTC)"
|
|
|
|
**Deprecated:** "**[Deprecated]** Use `newField` instead"
|
|
|
|
**Read-only:** "**Read-only.** Generated by the system"
|
|
|
|
## 4. Example Quality
|
|
|
|
### Request examples must:
|
|
- Use realistic data (not "foo", "bar")
|
|
- Include all required fields
|
|
- Be valid JSON
|
|
|
|
### Response examples must:
|
|
- Show complete structure
|
|
- Include all fields
|
|
- Use realistic UUIDs and timestamps
|
|
|
|
## 5. Dispatch Agent
|
|
|
|
For complex API documentation, dispatch the api-writer agent:
|
|
|
|
```
|
|
Task tool:
|
|
subagent_type: "ring-tw-team:api-writer"
|
|
model: "opus"
|
|
prompt: "Document the [endpoint] endpoint. Include:
|
|
- All path/query parameters
|
|
- Complete request body schema
|
|
- Complete response schema
|
|
- All error codes
|
|
- Realistic examples"
|
|
```
|
|
|
|
## 6. Review Before Publishing
|
|
|
|
After writing, use the docs-reviewer agent:
|
|
|
|
```
|
|
Task tool:
|
|
subagent_type: "ring-tw-team:docs-reviewer"
|
|
model: "opus"
|
|
prompt: "Review this API documentation for completeness and accuracy:
|
|
[paste documentation]"
|
|
```
|
|
|
|
## Data Types Reference
|
|
|
|
| Type | Description | Example |
|
|
|------|-------------|---------|
|
|
| `uuid` | UUID v4 | `3172933b-50d2-4b17-96aa-9b378d6a6eac` |
|
|
| `string` | Text | `"Customer Account"` |
|
|
| `integer` | Whole number | `42` |
|
|
| `boolean` | True/false | `true` |
|
|
| `timestamptz` | ISO 8601 (UTC) | `2024-01-15T10:30:00Z` |
|
|
| `jsonb` | JSON object | `{"key": "value"}` |
|
|
| `array` | List | `["item1", "item2"]` |
|
|
| `enum` | Predefined values | `currency`, `crypto` |
|
|
|
|
## HTTP Status Codes
|
|
|
|
**Success:** 200 (GET/PUT), 201 (POST), 204 (DELETE)
|
|
|
|
**Errors:** 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict), 422 (Invalid), 429 (Rate Limited), 500 (Server Error)
|
|
|
|
Now proceed with documenting: **$ARGUMENTS.endpoint**
|