Set up OpenAPI/Swagger documentation for all API endpoints #780
Description
Summary
Set up OpenAPI/Swagger documentation for all API endpoints in the Recollect project. This will provide an auto-generated, always up-to-date API reference that can be used by frontend developers and external integrations.
Related Slack discussion: https://timeless.slack.com/archives/C09139Z0Y75/p1771053045275089?thread_ts=1771049530.763939&cid=C09139Z0Y75
Motivation
- Generate updated API docs automatically when there are changes
- Provide a reliable API reference for frontend development
- Avoid confusion from typos or outdated endpoint information
- Documentation can reside in the repo itself
Current State
Total API Endpoints: 72
- App Router (
/src/app/api/): 29 endpoints - Pages Router (
/src/pages/api/): 43 endpoints
No existing OpenAPI/Swagger setup - Documentation framework needs to be created from scratch.
Endpoints by Feature
| Feature | App Router | Pages Router | Total |
|---|---|---|---|
| Bookmarks | 5 | 9 | 14 |
| Categories | 7 | 2 | 9 |
| Tags | 3 | 1 | 4 |
| Import (Twitter/Instagram/Raindrop) | 10 | - | 10 |
| Profiles | 1 | 6 | 7 |
| Sharing | - | 5 | 5 |
| Files | - | 2 | 2 |
| V1 API | - | 14 | 14 |
| Other | 3 | 4 | 7 |
Proposed Solution
1. Choose OpenAPI Library
Recommended: next-swagger-doc + swagger-ui-react
Alternatives:
@asteasolutions/zod-to-openapi- Generate from existing Zod schemasnext-openapi-route-handler- Native App Router support
2. Implementation Approach
Option A: JSDoc Comments (Minimal Changes)
Add JSDoc/OpenAPI comments to existing handlers.
Option B: Zod Schema Generation (Leverage Existing)
Since we already use Zod for validation, generate OpenAPI specs from existing schemas.
3. Documentation UI
Create an API docs page at /api-docs or /docs/api:
- Swagger UI for interactive testing
- Auto-reload in development
- Static generation for production
4. CI Integration
- Generate OpenAPI spec on build
- Validate spec is up-to-date in CI
- Optionally: Generate TypeScript client from spec
Tasks
- Choose and install OpenAPI library
- Set up documentation page route (
/api-docs) - Document App Router endpoints (29 endpoints)
- Document Pages Router endpoints (43 endpoints)
- Add authentication documentation
- Add error response documentation
- Add request/response examples
- Set up CI validation for spec
Existing Infrastructure to Leverage
- Response Helpers (
/src/lib/api-helpers/): Standardized{ data, error }patterns - Zod Schemas: Many endpoints have validation schemas convertible to OpenAPI
- Type Definitions (
/src/types/apiTypes.ts): 388 lines of comprehensive types
Acceptance Criteria
- All 72 API endpoints documented in OpenAPI 3.x format
- Interactive documentation UI accessible at
/api-docs - Documentation auto-updates when API changes
- Request/response schemas validated against actual code
- Authentication flow documented
- Error codes and responses documented