Document rate limit headers in OpenAPI spec

- Add reusable header components (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After)
- Reference headers in 200 responses on all conversion and demo endpoints
- Add Retry-After header to 429 responses
- Update Rate Limits section in API description to mention response headers
- Add comprehensive tests for header documentation (21 new tests)
- All 809 tests passing

src/swagger.ts

@@ -11,7 +11,7 @@ const options: swaggerJsdoc.Options = {
       title: "DocFast API",
       version,
       description:
-        "Convert HTML, Markdown, and URLs to pixel-perfect PDFs. Built-in invoice & receipt templates.\n\n## Authentication\nAll conversion endpoints require an API key via `Authorization: Bearer <key>` or `X-API-Key: <key>` header. Get your key at [docfast.dev](https://docfast.dev).\n\n## Rate Limits\n- Demo: 5 conversions/hour, watermarked output\n- Pro tier: 5,000 PDFs/month, 30 req/min\n\n## Getting Started\n1. Try the demo endpoints (no auth required, 5/hour limit)\n2. Upgrade to Pro at [docfast.dev](https://docfast.dev) for clean output and higher limits\n3. Use your API key to convert documents",
+        "Convert HTML, Markdown, and URLs to pixel-perfect PDFs. Built-in invoice & receipt templates.\n\n## Authentication\nAll conversion endpoints require an API key via `Authorization: Bearer <key>` or `X-API-Key: <key>` header. Get your key at [docfast.dev](https://docfast.dev).\n\n## Rate Limits\n- Demo: 5 conversions/hour, watermarked output\n- Pro tier: 5,000 PDFs/month, 30 req/min\n\nAll rate-limited endpoints return `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. On `429`, a `Retry-After` header indicates seconds until the next allowed request.\n\n## Getting Started\n1. Try the demo endpoints (no auth required, 5/hour limit)\n2. Upgrade to Pro at [docfast.dev](https://docfast.dev) for clean output and higher limits\n3. Use your API key to convert documents",
       contact: {
         name: "DocFast",
         url: "https://docfast.dev",
@@ -41,6 +41,36 @@ const options: swaggerJsdoc.Options = {
           description: "API key via X-API-Key header",
         },
       },
+      headers: {
+        "X-RateLimit-Limit": {
+          description: "The maximum number of requests allowed in the current time window",
+          schema: {
+            type: "integer",
+            example: 30,
+          },
+        },
+        "X-RateLimit-Remaining": {
+          description: "The number of requests remaining in the current time window",
+          schema: {
+            type: "integer",
+            example: 29,
+          },
+        },
+        "X-RateLimit-Reset": {
+          description: "Unix timestamp (seconds since epoch) when the rate limit window resets",
+          schema: {
+            type: "integer",
+            example: 1679875200,
+          },
+        },
+        "Retry-After": {
+          description: "Number of seconds to wait before retrying the request (returned on 429 responses)",
+          schema: {
+            type: "integer",
+            example: 60,
+          },
+        },
+      },
       schemas: {
         PdfOptions: {
           type: "object",