feat: wire up swagger-jsdoc dynamic spec, delete static openapi.json

- Create src/swagger.ts config module for swagger-jsdoc
- Add GET /openapi.json dynamic route (generated from @openapi annotations)
- Delete static public/openapi.json (was drifting from code)
- Add @openapi annotation for deprecated /v1/signup/free in index.ts
- Import swaggerSpec into index.ts
- All 12 endpoints now code-driven: demo/html, demo/markdown, convert/html,
  convert/markdown, convert/url, templates, templates/{id}/render,
  recover, recover/verify, billing/checkout, signup/free, health

dist/routes/templates.js

@@ -6,7 +6,53 @@ function sanitizeFilename(name) {
     return name.replace(/["\r\n\x00-\x1f]/g, "_").substring(0, 200);
 }
 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, res) => {
     const list = Object.entries(templates).map(([id, t]) => ({
         id,
@@ -16,7 +62,71 @@ templatesRouter.get("/", (_req, res) => {
     }));
     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, res) => {
     try {
         const id = req.params.id;