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

@@ -15,6 +15,46 @@ const recoverLimiter = rateLimit({
   legacyHeaders: false,
 });
 
+/**
+ * @openapi
+ * /v1/recover:
+ *   post:
+ *     tags: [Account]
+ *     summary: Request API key recovery
+ *     description: |
+ *       Sends a 6-digit verification code to the email address if an account exists.
+ *       Response is always the same regardless of whether the email exists (to prevent enumeration).
+ *       Rate limited to 3 requests per hour.
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [email]
+ *             properties:
+ *               email:
+ *                 type: string
+ *                 format: email
+ *                 description: Email address associated with the API key
+ *     responses:
+ *       200:
+ *         description: Recovery code sent (or no-op if email not found)
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 status:
+ *                   type: string
+ *                   example: recovery_sent
+ *                 message:
+ *                   type: string
+ *       400:
+ *         description: Invalid email format
+ *       429:
+ *         description: Too many recovery attempts
+ */
 router.post("/", recoverLimiter, async (req: Request, res: Response) => {
   const { email } = req.body || {};
 
@@ -41,6 +81,52 @@ router.post("/", recoverLimiter, async (req: Request, res: Response) => {
   res.json({ status: "recovery_sent", message: "If an account exists for this email, a verification code has been sent." });
 });
 
+/**
+ * @openapi
+ * /v1/recover/verify:
+ *   post:
+ *     tags: [Account]
+ *     summary: Verify recovery code and retrieve API key
+ *     description: Verifies the 6-digit code sent via email and returns the API key if valid. Code expires after 15 minutes.
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [email, code]
+ *             properties:
+ *               email:
+ *                 type: string
+ *                 format: email
+ *               code:
+ *                 type: string
+ *                 pattern: '^\d{6}$'
+ *                 description: 6-digit verification code
+ *     responses:
+ *       200:
+ *         description: API key recovered
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 status:
+ *                   type: string
+ *                   example: recovered
+ *                 apiKey:
+ *                   type: string
+ *                   description: The recovered API key
+ *                 tier:
+ *                   type: string
+ *                   enum: [free, pro]
+ *       400:
+ *         description: Invalid verification code or missing fields
+ *       410:
+ *         description: Verification code expired
+ *       429:
+ *         description: Too many failed attempts
+ */
 router.post("/verify", recoverLimiter, async (req: Request, res: Response) => {
   const { email, code } = req.body || {};