v0.4.1: Code-driven OpenAPI docs via swagger-jsdoc

- Add swagger-jsdoc dependency for auto-generating OpenAPI spec from JSDoc
- Add JSDoc @openapi annotations to all route handlers
- Create scripts/generate-openapi.mjs build step
- OpenAPI spec now auto-generated from code — no manual JSON editing
- All 13 endpoints documented with full parameters
- New demo endpoints documented, signup marked as deprecated
- Updated info description: demo-first, no free tier references
- Dockerfile updated to run openapi generation during build
- Build script updated: npm run build generates spec before compile

src/routes/templates.ts

@@ -9,7 +9,53 @@ function sanitizeFilename(name: string): string {
 
 export const templatesRouter = Router();
 
-// GET /v1/templates — list available templates
+/**
+ * @openapi
+ * /v1/templates:
+ *   get:
+ *     tags: [Templates]
+ *     summary: List available templates
+ *     description: Returns a list of all built-in document templates with their required fields.
+ *     security:
+ *       - BearerAuth: []
+ *       - ApiKeyHeader: []
+ *     responses:
+ *       200:
+ *         description: List of templates
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 templates:
+ *                   type: array
+ *                   items:
+ *                     type: object
+ *                     properties:
+ *                       id:
+ *                         type: string
+ *                         example: invoice
+ *                       name:
+ *                         type: string
+ *                         example: Invoice
+ *                       description:
+ *                         type: string
+ *                       fields:
+ *                         type: array
+ *                         items:
+ *                           type: object
+ *                           properties:
+ *                             name:
+ *                               type: string
+ *                             required:
+ *                               type: boolean
+ *                             description:
+ *                               type: string
+ *       401:
+ *         description: Missing API key
+ *       403:
+ *         description: Invalid API key
+ */
 templatesRouter.get("/", (_req: Request, res: Response) => {
   const list = Object.entries(templates).map(([id, t]) => ({
     id,
@@ -20,7 +66,71 @@ templatesRouter.get("/", (_req: Request, res: Response) => {
   res.json({ templates: list });
 });
 
-// POST /v1/templates/:id/render — render template to PDF
+/**
+ * @openapi
+ * /v1/templates/{id}/render:
+ *   post:
+ *     tags: [Templates]
+ *     summary: Render a template to PDF
+ *     description: |
+ *       Renders a built-in template with the provided data and returns a PDF.
+ *       Use GET /v1/templates to see available templates and their required fields.
+ *       Special fields: `_format` (page size), `_margin` (page margins), `_filename` (output filename).
+ *     security:
+ *       - BearerAuth: []
+ *       - ApiKeyHeader: []
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Template ID (e.g. "invoice", "receipt")
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               data:
+ *                 type: object
+ *                 description: Template data (fields depend on template). Can also be passed at root level.
+ *               _format:
+ *                 type: string
+ *                 enum: [A4, Letter, Legal, A3, A5, Tabloid]
+ *                 default: A4
+ *                 description: Page size override
+ *               _margin:
+ *                 type: object
+ *                 properties:
+ *                   top: { type: string }
+ *                   right: { type: string }
+ *                   bottom: { type: string }
+ *                   left: { type: string }
+ *                 description: Page margin override
+ *               _filename:
+ *                 type: string
+ *                 description: Custom output filename
+ *     responses:
+ *       200:
+ *         description: PDF document
+ *         content:
+ *           application/pdf:
+ *             schema:
+ *               type: string
+ *               format: binary
+ *       400:
+ *         description: Missing required template fields
+ *       401:
+ *         description: Missing API key
+ *       403:
+ *         description: Invalid API key
+ *       404:
+ *         description: Template not found
+ *       500:
+ *         description: Template rendering failed
+ */
 templatesRouter.post("/:id/render", async (req: Request, res: Response) => {
   try {
     const id = req.params.id as string;