Feature: Complete OpenAPI and Checked-In API Documentation

[3m1n3nc3]

Description

Make OpenAPI and checked-in documentation accurately represent every implemented route and convention.

File Location

learnault-api/src/config/swagger.ts, route/controller schemas, and learnault-api/docs/API.md

Design Reference

API Roadmap Phase 0: Complete OpenAPI and Checked-In API Documentation.

Dependencies

• Status: Blocked
• Blocked by: Feature: Standardize API Contracts Pagination and Versioning
• Blocks: Phase 0 closure and client integration

Tasks

• Define operation IDs, tags, security schemes, envelopes, pagination, and errors
• Document every current route, parameter, request, response, status, and authorization rule
• Remove or clearly mark unimplemented routes
• Add safe examples
• Add OpenAPI validation and route-to-spec coverage tests
• Document preview/update workflow

Acceptance Criteria

• Every non-health route maps to one OpenAPI operation
• Schemas match runtime behavior
• No fictional/stale endpoint is presented as implemented
• Validation and coverage pass

Verification Evidence

• Attach validation/coverage output and rendered Swagger screenshot or export

Difficulty

Advanced

[Menjay7]

Hi! I’m a full-stack developer with a strong blockchain background. I’d love to handle this issue and can deliver a clean, reliable solution. Kindly assign it to me.

[jaynomyaro]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. Thank you!

[teethaking]

Hey maintainer,
I'll step in and resolve this block on Phase 0 closure immediately. Out-of-sync API documentation is an absolute integration bottleneck—if the client SDK generators or frontend developers are building against spec schemas that deviate from actual runtime Express behavior (or if stale endpoints are left lying around), it leads to constant client-side integration failures.
Here is our direct implementation blueprint to align and enforce absolute parity in learnault-api:

1. Document Schema Synchronization

• Audit & Pruning: I will systematically inventory all active Express routers and controllers. Any stale, fictional, or partially implemented routes will be purged or explicitly sequestered behind a strict [UNIMPLEMENTED] marker in the spec.
• Envelopes, Pagination, & Errors: I will map the newly standardized pagination, versioning envelopes, and error objects into reusable OpenAPI component schemas (#/components/schemas/ErrorResponse, #/components/schemas/PaginatedResponse). Every operation will receive explicit parameter declarations, response status definitions, and bearer security requirements.

2. Implementation Workspace
   I will modify and align schemas across the following target files:

• learnault-api/src/config/swagger.ts (Global definitions, Swagger configuration, and metadata)
• learnault-api/docs/API.md (Human-readable overview of endpoints, versioning rules, and authentication flows)
• In-line controller schemas (Ensuring routing schemas directly match runtime Zod/Joi validation schemas)

3. Automated Route-to-Spec Coverage Testing
   To ensure the documentation never drifts out of sync again, I'll build a custom test wrapper (using jest/supertest and openapi-types or a validator library) that:

• Generates the runtime OpenAPI spec.
• Inspects the active Express router stack (app._router.stack).
• Compares and asserts that every registered non-health route has a matching OpenAPI Operation ID, path, and method, automatically breaking the build if a developer adds a route without documenting it.
  I'll run the validation and coverage sweeps locally and attach the raw test outputs and a Swagger rendering artifact in the PR description. Go ahead and assign this issue to me, and I'll clear this blocker!

[grantfox-oss]

🦊 GrantFox — @teethaking has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #71)
2. Your PR will be reviewed by the learnault maintainers

Good luck! Track your progress on GrantFox.