API Documentation Generator

Generate HTML API docs for Squint endpoints.

Investigation Process

Before writing docs, gather information from the codebase:

1. •Find the router - Search api/src/infrastructure/routes/ for the relevant router file
2. •Identify the handler - Find the handler function (e.g., GetProceduresHandler)
3. •Read the service - Located in api/src/infrastructure/services/ - understand request validation, query params, and response assembly
4. •Find response types - Check imports from @squintinc/datamodels-ts-cloud/v1 or look for Zod schemas
5. •Check repository - In api/src/infrastructure/repositories/ for SQL queries showing exact response shape
6. •Identify sub-objects - Note nested objects that need separate field tables

Documentation Structure

Each endpoint doc includes:

1. •Title: {HTTP_METHOD} {Endpoint Name} Endpoint
2. •Endpoint path: Full path pattern
3. •Description: 1-2 sentences explaining what the endpoint does
4. •Authentication: Bearer token requirement and required permission
5. •Request: Headers table, Path/Query Parameters tables, Request Body (if applicable)
6. •Response: Example JSON, Response Fields table, Sub-object tables
7. •Error Responses table

Field Type Conventions

Authentication Patterns

Integrations API (/v1/integrations/...)

For API key authentication, document as:

• •"Requires a valid API key with {permission} permission"
• •Format: Authorization: Bearer <prefix>:<secret>

Authenticated API (/v1/workspaces/...)

For Firebase JWT authentication, document as:

• •"Requires a valid workspace scoped Bearer token with {permission} permission"
• •Format: Authorization: Bearer <token>

JSON Example Guidelines

• •Use realistic fake UUIDs (e.g., f1e2d3c4-b5a6-7890-cdef-1234567890ab)
• •Use ISO 8601 timestamps (e.g., 2025-01-06T10:00:00.000Z)
• •Show null for nullable fields commonly null
• •Include 1-2 items for arrays
• •Show complete structure for nested objects

Output Location

Write HTML files to docs/api-docs/api/v1/:

docs/api-docs/api/v1/
├── integrations/workspaces/   # /v1/integrations/workspaces/{workspaceId}/...
└── workspaces/                # /v1/workspaces/{workspaceId}/...

Naming: {resource}.html or {resource}-{action}.html (e.g., tasks-create.html)

HTML Templates

See references/html-templates.md for:

• •Base HTML document structure
• •Table formats (Headers, Parameters, Response Fields, Errors)
• •Sub-object documentation patterns
• •Authentication section formats

Viewing Documentation

To preview HTML docs locally in VS Code/Cursor:

1. •Install the Live Preview extension
2. •Open any .html file
3. •Click "Show Preview" or right-click → "Live Preview: Show Preview"