Mark/devforge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Tech Debt: Add comprehensive API documentation #20

New issue
Closed
opened 2026-03-10 03:48:13 +00:00 by Mark · 2 comments
Mark commented 2026-03-10 03:48:13 +00:00
Owner
Copy link

Issue

API documentation exists via FastAPI auto-generated docs but lacks:

  • Usage examples
  • Error response details
  • Authentication flow documentation
  • Rate limiting info

Current State

  • Swagger UI at /docs
  • ReDoc at /redoc
  • But minimal custom documentation

Proposed Solution

  1. Expand OpenAPI descriptions with examples
  2. Create API usage guide
  3. Document all error codes
  4. Add authentication examples
  5. Postman/Insomnia collection

Acceptance Criteria

  • All endpoints have descriptive summaries
  • Request/response examples for all endpoints
  • Error code documentation
  • Authentication flow guide
  • Postman collection export
  • WebSocket documentation (terminal, events)
  • Changelog for API versions

Priority: Low
Type: Tech Debt / Documentation

## Issue API documentation exists via FastAPI auto-generated docs but lacks: - Usage examples - Error response details - Authentication flow documentation - Rate limiting info ## Current State - Swagger UI at `/docs` - ReDoc at `/redoc` - But minimal custom documentation ## Proposed Solution 1. Expand OpenAPI descriptions with examples 2. Create API usage guide 3. Document all error codes 4. Add authentication examples 5. Postman/Insomnia collection ## Acceptance Criteria - [ ] All endpoints have descriptive summaries - [ ] Request/response examples for all endpoints - [ ] Error code documentation - [ ] Authentication flow guide - [ ] Postman collection export - [ ] WebSocket documentation (terminal, events) - [ ] Changelog for API versions **Priority:** Low **Type:** Tech Debt / Documentation
Mark commented 2026-05-21 06:04:45 +00:00
Author
Owner
Copy link

GSD VERIFY phase failed after 3 attempts.
═══ Gate: verify-passed (devforge#20) ═══
Mode: Tier 1 (functional only)

GATE OK: All gates up to 'implement' pass
── Tier 1: Functional ────────────────────────────────
Running tests...
❌ Tests failed (exit 1)
 FAIL  services/web/src/utils/terminalUtils.test.ts > terminalUtils > decodeTerminalMessage > should return empty Uint8Array for Blob input in sync decoder
 FAIL  services/web/src/utils/terminalUtils.test.ts > terminalUtils > debug mode > should return false when debug is not enabled
 FAIL  services/web/src/utils/terminalUtils.test.ts > terminalUtils > debug mode > should return true when debug is enabled
 FAIL  services/web/src/utils/terminalUtils.test.ts > terminalUtils > debug mode > should disable debug mode
ReferenceError: localStorage is not defined
 ❯ services/web/src/utils/terminalUtils.test.ts:12:5
 10|  beforeEach(() => {
 11|  vi.restoreAllMocks();
 12|  localStorage.clear();
 |  ^
 13|  });
 14| 

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[4/9]⎯

 Test Files  4 failed | 1 passed (5)
 Tests  6 failed | 4 passed (10)
 Start at  23:04:42
 Duration  643ms (transform 456ms, setup 0ms, import 129ms, tests 9ms, environment 1ms)
Running linter...
✅ Lint clean
⚠️ No type checker discovered
Previous test count: unknown

❌ GATE FAIL: verify-passed
- Tests failed with exit code 1
GATE FAIL: verify — blocked at 2026-05-21T06:04:44Z
Class: test-failure
Evidence: Verification failed: 1 failures
Git tag: devforge#20-gate-verify-fail-d6eb85bbe555 (use gate-retry after fixing)

GSD VERIFY phase failed after 3 attempts. ═══ Gate: verify-passed (devforge#20) ═══ Mode: Tier 1 (functional only) GATE OK: All gates up to 'implement' pass ── Tier 1: Functional ──────────────────────────────── Running tests... ❌ Tests failed (exit 1)  FAIL  services/web/src/utils/terminalUtils.test.ts > terminalUtils > decodeTerminalMessage > should return empty Uint8Array for Blob input in sync decoder  FAIL  services/web/src/utils/terminalUtils.test.ts > terminalUtils > debug mode > should return false when debug is not enabled  FAIL  services/web/src/utils/terminalUtils.test.ts > terminalUtils > debug mode > should return true when debug is enabled  FAIL  services/web/src/utils/terminalUtils.test.ts > terminalUtils > debug mode > should disable debug mode ReferenceError: localStorage is not defined  ❯ services/web/src/utils/terminalUtils.test.ts:12:5  10|  beforeEach(() => {  11|  vi.restoreAllMocks();  12|  localStorage.clear();  |  ^  13|  });  14|  ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[4/9]⎯  Test Files  4 failed | 1 passed (5)  Tests  6 failed | 4 passed (10)  Start at  23:04:42  Duration  643ms (transform 456ms, setup 0ms, import 129ms, tests 9ms, environment 1ms) Running linter... ✅ Lint clean ⚠️ No type checker discovered Previous test count: unknown ❌ GATE FAIL: verify-passed - Tests failed with exit code 1 GATE FAIL: verify — blocked at 2026-05-21T06:04:44Z Class: test-failure Evidence: Verification failed: 1 failures Git tag: devforge#20-gate-verify-fail-d6eb85bbe555 (use gate-retry after fixing)
Mark commented 2026-06-01 12:01:13 +00:00
Author
Owner
Copy link

Fixed in commit. Closing.

Fixed in commit. Closing.
Mark closed this issue 2026-06-01 12:01:13 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels   
blocked:gate-plan

   
blocked:gate-research

   
blocked:lint-failed

   
blocked:needs-attention

Issue requires human attention to resolve

  
blocked:needs-decision

   
blocked:no-changes

   
blocked:no-procedure

   
blocked:verify-failed

   
bug

Bug report

  
chore

Config / cleanup / ops housekeeping

  
feature-request

   
in-progress

   
needs-research

Ready for research pipeline

  
ops-task

Operations task — install, configure, deploy, API calls

  
quickfix

   
security/medium

Medium severity security issue

  
triage-approved
No labels
blocked:gate-plan
blocked:gate-research
blocked:lint-failed
blocked:needs-attention
blocked:needs-decision
blocked:no-changes
blocked:no-procedure
blocked:verify-failed
bug
chore
feature-request
in-progress
needs-research
ops-task
quickfix
security/medium
triage-approved
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Mark/devforge#20
No description provided.