feat: add Swagger UI at /api-docs

package-lock.json

@@ -12,12 +12,19 @@
         "cors": "^2.8.5",
         "dotenv": "^16.4.5",
         "express": "^4.19.2",
-        "multer": "^2.0.1"
+        "multer": "^2.0.1",
+        "swagger-ui-express": "^5.0.1"
       },
       "engines": {
-        "node": ">=18"
+        "node": ">=22"
       }
     },
+    "node_modules/@scarf/scarf": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/@scarf/scarf/-/scarf-1.4.0.tgz",
+      "integrity": "sha512-xxeapPiUXdZAE3che6f3xogoJPeZgig6omHEy1rIY5WVsB3H2BHNnZH+gHG6x91SCWyQCzWGsuL2Hh3ClO5/qQ==",
+      "hasInstallScript": true
+    },
     "node_modules/@supabase/auth-js": {
       "version": "2.110.6",
       "resolved": "https://registry.npmjs.org/@supabase/auth-js/-/auth-js-2.110.6.tgz",
@@ -921,6 +928,28 @@
         "safe-buffer": "~5.2.0"
       }
     },
+    "node_modules/swagger-ui-dist": {
+      "version": "5.32.8",
+      "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-5.32.8.tgz",
+      "integrity": "sha512-dgMdWXIgnI4zX4OPhKEdWnlDODbgm8W3AX0Ivn/BBqcUh6xZsBxhZMnvk6DJyRz1BTrj8dPxtarmEGgkz30oyA==",
+      "dependencies": {
+        "@scarf/scarf": "=1.4.0"
+      }
+    },
+    "node_modules/swagger-ui-express": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/swagger-ui-express/-/swagger-ui-express-5.0.1.tgz",
+      "integrity": "sha512-SrNU3RiBGTLLmFU8GIJdOdanJTl4TOmT27tt3bWWHppqYmAZ6IDuEuBvMU6nZq0zLEe6b/1rACXCgLZqO6ZfrA==",
+      "dependencies": {
+        "swagger-ui-dist": ">=5.0.0"
+      },
+      "engines": {
+        "node": ">= v0.10.32"
+      },
+      "peerDependencies": {
+        "express": ">=4.0.0 || >=5.0.0-beta"
+      }
+    },
     "node_modules/toidentifier": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz",

package.json

@@ -16,6 +16,7 @@
     "cors": "^2.8.5",
     "dotenv": "^16.4.5",
     "express": "^4.19.2",
-    "multer": "^2.0.1"
+    "multer": "^2.0.1",
+    "swagger-ui-express": "^5.0.1"
   }
 }

server.js

@@ -3,10 +3,12 @@ import cors from 'cors';
 import { fileURLToPath } from 'url';
 import path from 'path';
 import dotenv from 'dotenv';
+import swaggerUi from 'swagger-ui-express';
 
 import projectsRouter from './src/routes/projects.js';
 import ticketsRouter from './src/routes/tickets.js';
 import flowRouter from './src/routes/flow.js';
+import { openapiSpec } from './src/openapi.js';
 
 dotenv.config();
 
@@ -26,6 +28,12 @@ app.use('/flow/tickets', flowRouter);
 
 app.get('/api/health', (req, res) => res.json({ ok: true }));
 
+// API documentation (Swagger UI) + raw OpenAPI spec
+app.get('/api-docs.json', (req, res) => res.json(openapiSpec));
+app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(openapiSpec, {
+  customSiteTitle: 'Taboard API Docs'
+}));
+
 // Static frontend
 app.use(express.static(path.join(__dirname, 'public')));
 

src/openapi.js

@@ -0,0 +1,405 @@
+// OpenAPI 3.0 specification for the Taboard API, served via Swagger UI at /api-docs.
+const STATUSES = ['open', 'queued', 'processing', 'done', 'failed', 'close'];
+const TYPES = ['backend', 'api', 'frontend', 'ui'];
+
+export const openapiSpec = {
+  openapi: '3.0.3',
+  info: {
+    title: 'Taboard API',
+    version: '1.0.0',
+    description: 'Jira-style admin board + API backed by Supabase.'
+  },
+  tags: [
+    { name: 'Health', description: 'Service health' },
+    { name: 'Projects', description: 'Project management' },
+    { name: 'Tickets', description: 'Ticket management (board)' },
+    { name: 'Flow', description: 'Lightweight ticket flow API for agents' }
+  ],
+  components: {
+    schemas: {
+      Error: {
+        type: 'object',
+        properties: { error: { type: 'string' } }
+      },
+      Project: {
+        type: 'object',
+        properties: {
+          id: { type: 'integer', readOnly: true },
+          name: { type: 'string' },
+          note: { type: 'string', nullable: true },
+          struc: { type: 'object', additionalProperties: true }
+        }
+      },
+      ProjectInput: {
+        type: 'object',
+        required: ['name'],
+        properties: {
+          name: { type: 'string' },
+          note: { type: 'string', nullable: true },
+          struc: {
+            oneOf: [{ type: 'object' }, { type: 'string' }],
+            description: 'Object, or a JSON string (parsed server-side).'
+          }
+        }
+      },
+      Ticket: {
+        type: 'object',
+        properties: {
+          id: { type: 'integer', readOnly: true },
+          title: { type: 'string' },
+          detail: { type: 'string', nullable: true },
+          type: { type: 'string', enum: TYPES },
+          status: { type: 'string', enum: STATUSES },
+          message: { type: 'string', nullable: true },
+          logs: { type: 'string', nullable: true },
+          sort: { type: 'integer' },
+          subtic: { type: 'integer', nullable: true },
+          projectid: { type: 'integer', nullable: true },
+          images: { type: 'array', items: { type: 'string', format: 'uri' } }
+        }
+      },
+      TicketInput: {
+        type: 'object',
+        required: ['title'],
+        properties: {
+          title: { type: 'string' },
+          detail: { type: 'string', nullable: true },
+          type: { type: 'string', enum: TYPES, default: 'backend' },
+          status: { type: 'string', enum: STATUSES, default: 'open' },
+          message: { type: 'string', nullable: true },
+          logs: { type: 'string', nullable: true },
+          sort: { type: 'integer', default: 0 },
+          subtic: { type: 'integer', nullable: true },
+          projectid: { type: 'integer', nullable: true }
+        }
+      },
+      FlowTicket: {
+        type: 'object',
+        properties: {
+          id: { type: 'integer' },
+          title: { type: 'string' },
+          detail: { type: 'string', nullable: true },
+          status: { type: 'string', enum: STATUSES },
+          message: { type: 'string', nullable: true }
+        }
+      },
+      FlowUpdate: {
+        type: 'object',
+        required: ['id'],
+        properties: {
+          id: { type: 'integer' },
+          status: { type: 'string', enum: STATUSES },
+          message: { type: 'string' },
+          detail: { type: 'string' }
+        }
+      }
+    },
+    responses: {
+      NotFound: {
+        description: 'Not found',
+        content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } }
+      },
+      BadRequest: {
+        description: 'Invalid request',
+        content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } }
+      },
+      ServerError: {
+        description: 'Server error',
+        content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } }
+      }
+    }
+  },
+  paths: {
+    '/api/health': {
+      get: {
+        tags: ['Health'],
+        summary: 'Health check',
+        responses: {
+          200: {
+            description: 'OK',
+            content: {
+              'application/json': {
+                schema: { type: 'object', properties: { ok: { type: 'boolean' } } }
+              }
+            }
+          }
+        }
+      }
+    },
+    '/api/projects': {
+      get: {
+        tags: ['Projects'],
+        summary: 'List projects',
+        responses: {
+          200: {
+            description: 'Array of projects',
+            content: {
+              'application/json': {
+                schema: { type: 'array', items: { $ref: '#/components/schemas/Project' } }
+              }
+            }
+          },
+          500: { $ref: '#/components/responses/ServerError' }
+        }
+      },
+      post: {
+        tags: ['Projects'],
+        summary: 'Create project',
+        requestBody: {
+          required: true,
+          content: { 'application/json': { schema: { $ref: '#/components/schemas/ProjectInput' } } }
+        },
+        responses: {
+          201: {
+            description: 'Created',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/Project' } } }
+          },
+          400: { $ref: '#/components/responses/BadRequest' },
+          500: { $ref: '#/components/responses/ServerError' }
+        }
+      }
+    },
+    '/api/projects/{id}': {
+      parameters: [
+        { name: 'id', in: 'path', required: true, schema: { type: 'integer' } }
+      ],
+      get: {
+        tags: ['Projects'],
+        summary: 'Get project',
+        responses: {
+          200: {
+            description: 'Project',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/Project' } } }
+          },
+          404: { $ref: '#/components/responses/NotFound' }
+        }
+      },
+      put: {
+        tags: ['Projects'],
+        summary: 'Update project',
+        requestBody: {
+          required: true,
+          content: { 'application/json': { schema: { $ref: '#/components/schemas/ProjectInput' } } }
+        },
+        responses: {
+          200: {
+            description: 'Updated',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/Project' } } }
+          },
+          500: { $ref: '#/components/responses/ServerError' }
+        }
+      },
+      delete: {
+        tags: ['Projects'],
+        summary: 'Delete project',
+        responses: {
+          204: { description: 'Deleted' },
+          500: { $ref: '#/components/responses/ServerError' }
+        }
+      }
+    },
+    '/api/tickets': {
+      get: {
+        tags: ['Tickets'],
+        summary: 'List tickets',
+        parameters: [
+          {
+            name: 'subtic', in: 'query',
+            schema: { type: 'string' },
+            description: 'Filter by parent ticket id, or "null" for top-level tickets.'
+          },
+          {
+            name: 'projectid', in: 'query',
+            schema: { type: 'integer' },
+            description: 'Filter by project id.'
+          }
+        ],
+        responses: {
+          200: {
+            description: 'Array of tickets',
+            content: {
+              'application/json': {
+                schema: { type: 'array', items: { $ref: '#/components/schemas/Ticket' } }
+              }
+            }
+          },
+          500: { $ref: '#/components/responses/ServerError' }
+        }
+      },
+      post: {
+        tags: ['Tickets'],
+        summary: 'Create ticket',
+        requestBody: {
+          required: true,
+          content: { 'application/json': { schema: { $ref: '#/components/schemas/TicketInput' } } }
+        },
+        responses: {
+          201: {
+            description: 'Created',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/Ticket' } } }
+          },
+          400: { $ref: '#/components/responses/BadRequest' },
+          500: { $ref: '#/components/responses/ServerError' }
+        }
+      }
+    },
+    '/api/tickets/{id}': {
+      parameters: [
+        { name: 'id', in: 'path', required: true, schema: { type: 'integer' } }
+      ],
+      get: {
+        tags: ['Tickets'],
+        summary: 'Get ticket',
+        responses: {
+          200: {
+            description: 'Ticket',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/Ticket' } } }
+          },
+          404: { $ref: '#/components/responses/NotFound' }
+        }
+      },
+      put: {
+        tags: ['Tickets'],
+        summary: 'Update ticket',
+        requestBody: {
+          required: true,
+          content: { 'application/json': { schema: { $ref: '#/components/schemas/TicketInput' } } }
+        },
+        responses: {
+          200: {
+            description: 'Updated',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/Ticket' } } }
+          },
+          400: { $ref: '#/components/responses/BadRequest' },
+          500: { $ref: '#/components/responses/ServerError' }
+        }
+      },
+      delete: {
+        tags: ['Tickets'],
+        summary: 'Delete ticket (sub-tickets cascade)',
+        responses: {
+          204: { description: 'Deleted' },
+          500: { $ref: '#/components/responses/ServerError' }
+        }
+      }
+    },
+    '/api/tickets/{id}/images': {
+      parameters: [
+        { name: 'id', in: 'path', required: true, schema: { type: 'integer' } }
+      ],
+      post: {
+        tags: ['Tickets'],
+        summary: 'Upload ticket images',
+        requestBody: {
+          required: true,
+          content: {
+            'multipart/form-data': {
+              schema: {
+                type: 'object',
+                properties: {
+                  images: {
+                    type: 'array',
+                    items: { type: 'string', format: 'binary' }
+                  }
+                }
+              }
+            }
+          }
+        },
+        responses: {
+          201: {
+            description: 'Ticket with appended image URLs',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/Ticket' } } }
+          },
+          400: { $ref: '#/components/responses/BadRequest' },
+          404: { $ref: '#/components/responses/NotFound' },
+          500: { $ref: '#/components/responses/ServerError' }
+        }
+      },
+      delete: {
+        tags: ['Tickets'],
+        summary: 'Remove one image URL from a ticket',
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                required: ['url'],
+                properties: { url: { type: 'string', format: 'uri' } }
+              }
+            }
+          }
+        },
+        responses: {
+          200: {
+            description: 'Updated ticket',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/Ticket' } } }
+          },
+          400: { $ref: '#/components/responses/BadRequest' },
+          404: { $ref: '#/components/responses/NotFound' },
+          500: { $ref: '#/components/responses/ServerError' }
+        }
+      }
+    },
+    '/flow/tickets': {
+      get: {
+        tags: ['Flow'],
+        summary: 'List tickets (id, title, status)',
+        responses: {
+          200: {
+            description: 'Array of flow tickets',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      id: { type: 'integer' },
+                      title: { type: 'string' },
+                      status: { type: 'string', enum: STATUSES }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          500: { $ref: '#/components/responses/ServerError' }
+        }
+      },
+      put: {
+        tags: ['Flow'],
+        summary: 'Update ticket status/message/detail',
+        requestBody: {
+          required: true,
+          content: { 'application/json': { schema: { $ref: '#/components/schemas/FlowUpdate' } } }
+        },
+        responses: {
+          200: {
+            description: 'Updated ticket',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/Ticket' } } }
+          },
+          400: { $ref: '#/components/responses/BadRequest' },
+          500: { $ref: '#/components/responses/ServerError' }
+        }
+      }
+    },
+    '/flow/tickets/{id}': {
+      parameters: [
+        { name: 'id', in: 'path', required: true, schema: { type: 'integer' } }
+      ],
+      get: {
+        tags: ['Flow'],
+        summary: 'Get ticket (id, title, detail, status, message)',
+        responses: {
+          200: {
+            description: 'Flow ticket',
+            content: { 'application/json': { schema: { $ref: '#/components/schemas/FlowTicket' } } }
+          },
+          404: { $ref: '#/components/responses/NotFound' }
+        }
+      }
+    }
+  }
+};