Initial commit

2025-11-30 08:37:25 +08:00
commit 71961f9eff
18 changed files with 3314 additions and 0 deletions
--- a/skills/writing-api-docs/SKILL.md
+++ b/skills/writing-api-docs/SKILL.md
@@ -0,0 +1,339 @@
+---
+name: writing-api-docs
+description: |
+  Patterns and structure for writing API reference documentation including
+  endpoint descriptions, request/response schemas, and error documentation.
+
+trigger: |
+  - Documenting REST API endpoints
+  - Writing request/response examples
+  - Documenting error codes
+  - Creating API field descriptions
+
+skip_when: |
+  - Writing conceptual guides → use writing-functional-docs
+  - Reviewing documentation → use documentation-review
+  - Writing code → use dev-team agents
+
+sequence:
+  before: [documentation-review]
+
+related:
+  similar: [writing-functional-docs]
+  complementary: [api-field-descriptions, documentation-structure]
+---
+
+# Writing API Reference Documentation
+
+API reference documentation describes what each endpoint does, its parameters, request/response formats, and error conditions. It focuses on the "what" rather than the "why."
+
+---
+
+## API Reference Principles
+
+### RESTful and Predictable
+- Follow standard HTTP methods and status codes
+- Use consistent URL patterns
+- Document idempotency behavior
+
+### Consistent Formats
+- Requests and responses use JSON
+- Clear typing and structures
+- Standard error format
+
+### Explicit Versioning
+- Document version in URL path
+- Note backward compatibility
+- Mark deprecated fields clearly
+
+---
+
+## Endpoint Documentation Structure
+
+### Basic Structure
+
+```markdown
+# Endpoint Name
+
+Brief description of what this endpoint does.
+
+## Request
+
+### HTTP Method and Path
+
+`POST /v1/organizations/{organizationId}/ledgers/{ledgerId}/accounts`
+
+### Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| organizationId | uuid | Yes | The unique identifier of the Organization |
+| ledgerId | uuid | Yes | The unique identifier of the Ledger |
+
+### Request Body
+
+```json
+{
+  "name": "string",
+  "assetCode": "string",
+  "type": "string"
+}
+```
+
+### Request Body Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | Yes | The name of the Account |
+| assetCode | string | Yes | The code of the Asset (e.g., "BRL", "USD") |
+| type | string | No | The account type classification |
+
+## Response
+
+### Success Response (201 Created)
+
+```json
+{
+  "id": "3172933b-50d2-4b17-96aa-9b378d6a6eac",
+  "name": "Customer Account",
+  "assetCode": "BRL",
+  "status": {
+    "code": "ACTIVE"
+  },
+  "createdAt": "2024-01-15T10:30:00Z"
+}
+```
+
+### Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | uuid | The unique identifier of the created Account |
+| name | string | The name of the Account |
+| createdAt | timestamptz | Timestamp of creation (UTC) |
+
+## Errors
+
+| Status Code | Error Code | Description |
+|-------------|------------|-------------|
+| 400 | INVALID_REQUEST | Request body validation failed |
+| 404 | LEDGER_NOT_FOUND | The specified Ledger does not exist |
+| 409 | ACCOUNT_EXISTS | An account with this alias already exists |
+```
+
+---
+
+## Field Description Patterns
+
+### Basic Field Description
+
+```markdown
+| name | string | The name of the Account |
+```
+
+### Field with Constraints
+
+```markdown
+| code | string | The asset code (max 10 characters, uppercase) |
+```
+
+### Field with Example
+
+```markdown
+| email | string | User email address (e.g., "user@example.com") |
+```
+
+### Required vs Optional
+
+```markdown
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | Yes | The name of the Account |
+| alias | string | No | A user-friendly identifier. If omitted, uses the account ID |
+```
+
+### Deprecated Fields
+
+```markdown
+| chartOfAccountsGroupName | string | **[Deprecated]** Use `route` instead. The name of the group. |
+```
+
+---
+
+## Data Types Reference
+
+Use consistent type names across all documentation:
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `uuid` | UUID v4 identifier | `3172933b-50d2-4b17-96aa-9b378d6a6eac` |
+| `string` | Text value | `"Customer Account"` |
+| `text` | Long text value | `"Detailed description..."` |
+| `integer` | Whole number | `42` |
+| `boolean` | True/false value | `true` |
+| `timestamptz` | ISO 8601 timestamp (UTC) | `2024-01-15T10:30:00Z` |
+| `jsonb` | JSON object | `{"key": "value"}` |
+| `array` | List of values | `["item1", "item2"]` |
+| `enum` | One of predefined values | `currency`, `crypto`, `commodity` |
+
+---
+
+## Request/Response Examples
+
+### Complete Request Example
+
+Always show a realistic, working example:
+
+```json
+{
+  "name": "João Silva - Checking",
+  "assetCode": "BRL",
+  "type": "checking",
+  "alias": "@joao_checking",
+  "metadata": {
+    "customerId": "cust_123456",
+    "branch": "0001"
+  }
+}
+```
+
+### Complete Response Example
+
+Show all fields that would be returned:
+
+```json
+{
+  "id": "3172933b-50d2-4b17-96aa-9b378d6a6eac",
+  "organizationId": "7c3e4f2a-1b8d-4e5c-9f0a-2d3e4f5a6b7c",
+  "ledgerId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
+  "name": "João Silva - Checking",
+  "assetCode": "BRL",
+  "type": "checking",
+  "alias": "@joao_checking",
+  "status": {
+    "code": "ACTIVE",
+    "description": null
+  },
+  "metadata": {
+    "customerId": "cust_123456",
+    "branch": "0001"
+  },
+  "createdAt": "2024-01-15T10:30:00Z",
+  "updatedAt": "2024-01-15T10:30:00Z",
+  "deletedAt": null
+}
+```
+
+---
+
+## Error Documentation
+
+### Standard Error Format
+
+```json
+{
+  "code": "ACCOUNT_NOT_FOUND",
+  "message": "The specified account does not exist",
+  "details": {
+    "accountId": "invalid-uuid"
+  }
+}
+```
+
+### Error Table Format
+
+| Status Code | Error Code | Description | Resolution |
+|-------------|------------|-------------|------------|
+| 400 | INVALID_REQUEST | Request validation failed | Check request body format |
+| 401 | UNAUTHORIZED | Missing or invalid authentication | Provide valid API key |
+| 403 | FORBIDDEN | Insufficient permissions | Contact admin for access |
+| 404 | NOT_FOUND | Resource does not exist | Verify the resource ID |
+| 409 | CONFLICT | Resource already exists | Use a different identifier |
+| 422 | UNPROCESSABLE_ENTITY | Business rule violation | Check business constraints |
+| 500 | INTERNAL_ERROR | Server error | Retry or contact support |
+
+---
+
+## HTTP Status Codes
+
+### Success Codes
+
+| Code | Usage |
+|------|-------|
+| 200 OK | Successful GET, PUT, PATCH |
+| 201 Created | Successful POST that creates a resource |
+| 204 No Content | Successful DELETE |
+
+### Error Codes
+
+| Code | Usage |
+|------|-------|
+| 400 Bad Request | Malformed request syntax |
+| 401 Unauthorized | Missing or invalid authentication |
+| 403 Forbidden | Valid auth but insufficient permissions |
+| 404 Not Found | Resource does not exist |
+| 409 Conflict | Resource state conflict (e.g., duplicate) |
+| 422 Unprocessable Entity | Valid syntax but invalid semantics |
+| 429 Too Many Requests | Rate limit exceeded |
+| 500 Internal Server Error | Server-side error |
+
+---
+
+## Pagination Documentation
+
+When an endpoint returns paginated results:
+
+```markdown
+### Query Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| limit | integer | 10 | Number of results per page (max 100) |
+| page | integer | 1 | Page number to retrieve |
+
+### Pagination Response
+
+```json
+{
+  "items": [...],
+  "page": 1,
+  "limit": 10,
+  "totalItems": 150,
+  "totalPages": 15
+}
+```
+```
+
+---
+
+## API Versioning Notes
+
+When documenting versioned APIs:
+
+```markdown
+> **Note:** You're viewing documentation for the **current version** (v3).
+> For previous versions, use the version switcher.
+```
+
+For deprecated endpoints:
+
+```markdown
+> **Deprecated:** This endpoint will be removed in v4. Use [/v3/accounts](link) instead.
+```
+
+---
+
+## Quality Checklist
+
+Before finishing API documentation, verify:
+
+- [ ] HTTP method and path are correct
+- [ ] All path parameters documented
+- [ ] All query parameters documented
+- [ ] All request body fields documented with types
+- [ ] All response fields documented with types
+- [ ] Required vs optional fields are clear
+- [ ] Realistic request/response examples included
+- [ ] All error codes documented
+- [ ] Deprecated fields are marked
+- [ ] Links to related endpoints included