docs: add X-Render-Time header to OpenAPI spec

public/openapi.json

@@ -310,6 +310,9 @@
               },
               "X-RateLimit-Reset": {
                 "$ref": "#/components/headers/X-RateLimit-Reset"
+              },
+              "X-Render-Time": {
+                "$ref": "#/components/headers/X-Render-Time"
               }
             },
             "content": {
@@ -405,6 +408,9 @@
               },
               "X-RateLimit-Reset": {
                 "$ref": "#/components/headers/X-RateLimit-Reset"
+              },
+              "X-Render-Time": {
+                "$ref": "#/components/headers/X-Render-Time"
               }
             },
             "content": {
@@ -508,6 +514,9 @@
               },
               "X-RateLimit-Reset": {
                 "$ref": "#/components/headers/X-RateLimit-Reset"
+              },
+              "X-Render-Time": {
+                "$ref": "#/components/headers/X-Render-Time"
               }
             },
             "content": {
@@ -595,6 +604,9 @@
               },
               "X-RateLimit-Reset": {
                 "$ref": "#/components/headers/X-RateLimit-Reset"
+              },
+              "X-Render-Time": {
+                "$ref": "#/components/headers/X-Render-Time"
               }
             },
             "content": {
@@ -693,6 +705,9 @@
               },
               "X-RateLimit-Reset": {
                 "$ref": "#/components/headers/X-RateLimit-Reset"
+              },
+              "X-Render-Time": {
+                "$ref": "#/components/headers/X-Render-Time"
               }
             },
             "content": {

src/__tests__/openapi-spec.test.ts

@@ -96,6 +96,32 @@ describe("OpenAPI spec accuracy", () => {
       });
     });
 
+    const allConversionEndpoints = [
+      "/v1/convert/html",
+      "/v1/convert/markdown",
+      "/v1/convert/url",
+      "/v1/demo/html",
+      "/v1/demo/markdown",
+    ];
+
+    describe("X-Render-Time header", () => {
+      it("should define X-Render-Time header component", () => {
+        expect(spec.components.headers["X-Render-Time"]).toBeDefined();
+        expect(spec.components.headers["X-Render-Time"].schema.type).toBe("integer");
+        expect(spec.components.headers["X-Render-Time"].description).toContain("render time");
+      });
+
+      allConversionEndpoints.forEach((endpoint) => {
+        it(`${endpoint} 200 response should include X-Render-Time header`, () => {
+          const response200 = spec.paths[endpoint]?.post?.responses["200"];
+          expect(response200.headers["X-Render-Time"]).toBeDefined();
+          expect(response200.headers["X-Render-Time"].$ref).toBe(
+            "#/components/headers/X-Render-Time"
+          );
+        });
+      });
+    });
+
     it("should mention rate limit headers in API description", () => {
       const description = spec.info.description;
       expect(description).toContain("X-RateLimit-Limit");

src/routes/convert.ts

@@ -47,6 +47,8 @@ export const convertRouter = Router();
  *             $ref: '#/components/headers/X-RateLimit-Remaining'
  *           X-RateLimit-Reset:
  *             $ref: '#/components/headers/X-RateLimit-Reset'
+ *           X-Render-Time:
+ *             $ref: '#/components/headers/X-Render-Time'
  *         content:
  *           application/pdf:
  *             schema:
@@ -120,6 +122,8 @@ convertRouter.post("/html", async (req: Request, res: Response) => {
  *             $ref: '#/components/headers/X-RateLimit-Remaining'
  *           X-RateLimit-Reset:
  *             $ref: '#/components/headers/X-RateLimit-Reset'
+ *           X-Render-Time:
+ *             $ref: '#/components/headers/X-Render-Time'
  *         content:
  *           application/pdf:
  *             schema:
@@ -196,6 +200,8 @@ convertRouter.post("/markdown", async (req: Request, res: Response) => {
  *             $ref: '#/components/headers/X-RateLimit-Remaining'
  *           X-RateLimit-Reset:
  *             $ref: '#/components/headers/X-RateLimit-Reset'
+ *           X-Render-Time:
+ *             $ref: '#/components/headers/X-Render-Time'
  *         content:
  *           application/pdf:
  *             schema:

src/routes/demo.ts

@@ -108,6 +108,8 @@ interface DemoBody {
  *             $ref: '#/components/headers/X-RateLimit-Remaining'
  *           X-RateLimit-Reset:
  *             $ref: '#/components/headers/X-RateLimit-Reset'
+ *           X-Render-Time:
+ *             $ref: '#/components/headers/X-Render-Time'
  *         content:
  *           application/pdf:
  *             schema:
@@ -204,6 +206,8 @@ router.post("/html", async (req: Request, res: Response) => {
  *             $ref: '#/components/headers/X-RateLimit-Remaining'
  *           X-RateLimit-Reset:
  *             $ref: '#/components/headers/X-RateLimit-Reset'
+ *           X-Render-Time:
+ *             $ref: '#/components/headers/X-Render-Time'
  *         content:
  *           application/pdf:
  *             schema:

src/swagger.ts

@@ -63,6 +63,13 @@ const options: swaggerJsdoc.Options = {
             example: 1679875200,
           },
         },
+        "X-Render-Time": {
+          description: "PDF render time in milliseconds",
+          schema: {
+            type: "integer",
+            example: 120,
+          },
+        },
         "Retry-After": {
           description: "Number of seconds to wait before retrying the request (returned on 429 responses)",
           schema: {