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/demo.ts

@@ -42,7 +42,59 @@ function sanitizeFilename(name: string): string {
   return name.replace(/[\x00-\x1f"\\\r\n]/g, "").trim() || "document.pdf";
 }
 
-// POST /v1/demo/html
+/**
+ * @openapi
+ * /v1/demo/html:
+ *   post:
+ *     tags: [Demo]
+ *     summary: Convert HTML to PDF (demo)
+ *     description: |
+ *       Public endpoint — no API key required. Rate limited to 5 requests per hour per IP.
+ *       Output PDFs include a DocFast watermark. Upgrade to Pro for clean output.
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             allOf:
+ *               - type: object
+ *                 required: [html]
+ *                 properties:
+ *                   html:
+ *                     type: string
+ *                     description: HTML content to convert
+ *                     example: '<h1>Hello World</h1><p>My first PDF</p>'
+ *                   css:
+ *                     type: string
+ *                     description: Optional CSS to inject (used when html is a fragment)
+ *               - $ref: '#/components/schemas/PdfOptions'
+ *     responses:
+ *       200:
+ *         description: Watermarked PDF document
+ *         content:
+ *           application/pdf:
+ *             schema:
+ *               type: string
+ *               format: binary
+ *       400:
+ *         description: Missing html field
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       415:
+ *         description: Unsupported Content-Type
+ *       429:
+ *         description: Demo rate limit exceeded (5/hour)
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       503:
+ *         description: Server busy
+ *       504:
+ *         description: PDF generation timed out
+ */
 router.post("/html", async (req: Request & { acquirePdfSlot?: () => Promise<void>; releasePdfSlot?: () => void }, res: Response) => {
   let slotAcquired = false;
   try {
@@ -93,7 +145,51 @@ router.post("/html", async (req: Request & { acquirePdfSlot?: () => Promise<void
   }
 });
 
-// POST /v1/demo/markdown
+/**
+ * @openapi
+ * /v1/demo/markdown:
+ *   post:
+ *     tags: [Demo]
+ *     summary: Convert Markdown to PDF (demo)
+ *     description: |
+ *       Public endpoint — no API key required. Rate limited to 5 requests per hour per IP.
+ *       Markdown is converted to HTML then rendered to PDF with a DocFast watermark.
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             allOf:
+ *               - type: object
+ *                 required: [markdown]
+ *                 properties:
+ *                   markdown:
+ *                     type: string
+ *                     description: Markdown content to convert
+ *                     example: '# Hello World\n\nThis is **bold** and *italic*.'
+ *                   css:
+ *                     type: string
+ *                     description: Optional CSS to inject
+ *               - $ref: '#/components/schemas/PdfOptions'
+ *     responses:
+ *       200:
+ *         description: Watermarked PDF document
+ *         content:
+ *           application/pdf:
+ *             schema:
+ *               type: string
+ *               format: binary
+ *       400:
+ *         description: Missing markdown field
+ *       415:
+ *         description: Unsupported Content-Type
+ *       429:
+ *         description: Demo rate limit exceeded (5/hour)
+ *       503:
+ *         description: Server busy
+ *       504:
+ *         description: PDF generation timed out
+ */
 router.post("/markdown", async (req: Request & { acquirePdfSlot?: () => Promise<void>; releasePdfSlot?: () => void }, res: Response) => {
   let slotAcquired = false;
   try {