test(api): add integration tests for API docs endpoint

Also update GitHub Pages REST API doc to link to /api/docs.

apps/docs/api/rest.md

@@ -1,6 +1,12 @@
 # REST API
 
-The API server runs on port 1349 by default and serves all endpoints under `/api`. Interactive Swagger documentation is available at `/api/docs` when the server is running.
+The API server runs on port 1349 by default and serves all endpoints under `/api`.
+
+::: tip Interactive API Reference
+When your Stirling Image instance is running, visit [`/api/docs`](http://localhost:1349/api/docs) for an interactive API reference with full endpoint documentation, request schemas, and response examples.
+:::
+
+The reference below covers the key endpoints. For the complete specification, see the interactive docs.
 
 ## Authentication
 

tests/integration/docs.test.ts

@@ -0,0 +1,53 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { buildTestApp, type TestApp } from "./test-server";
+
+describe("API docs", () => {
+  let testApp: TestApp;
+
+  beforeAll(async () => {
+    testApp = await buildTestApp();
+  });
+
+  afterAll(async () => {
+    await testApp.cleanup();
+  });
+
+  it("serves the OpenAPI spec as YAML", async () => {
+    const res = await testApp.app.inject({
+      method: "GET",
+      url: "/api/v1/openapi.yaml",
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.headers["content-type"]).toContain("text/yaml");
+    expect(res.body).toContain("openapi: 3.1.0");
+    expect(res.body).toContain("Stirling Image API");
+  });
+
+  it("serves the Scalar docs page without auth", async () => {
+    // Scalar redirects /api/docs -> /api/docs/ (trailing slash)
+    const redirect = await testApp.app.inject({
+      method: "GET",
+      url: "/api/docs",
+    });
+    expect([200, 301, 302]).toContain(redirect.statusCode);
+
+    const res = await testApp.app.inject({
+      method: "GET",
+      url: "/api/docs/",
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.headers["content-type"]).toContain("text/html");
+  });
+
+  it("includes all tool endpoints in the spec", async () => {
+    const res = await testApp.app.inject({
+      method: "GET",
+      url: "/api/v1/openapi.yaml",
+    });
+    const body = res.body;
+    expect(body).toContain("/api/v1/tools/resize");
+    expect(body).toContain("/api/v1/tools/compress");
+    expect(body).toContain("/api/v1/tools/remove-background");
+    expect(body).toContain("/api/v1/tools/ocr");
+  });
+});