docs: Update OpenAPI docs, adding descriptions and examples to everything

Author: aklinker1

src/@types/modules.d.ts

@@ -4,6 +4,11 @@ declare module "*.gql" {
 }
 
 declare module "*.tmpl" {
-  const content: string;
-  export default content;
+  const text: string;
+  export default text;
+}
+
+declare module "*.md" {
+  const text: string;
+  export default text;
 }

src/assets/api-reference-description.md

@@ -0,0 +1,12 @@
+# Overview
+
+As of right now, there the WXT Queue API is free to use with no authentication requirements.
+
+> [!IMPORTANT]
+> If you want to keep it this way, **be respectful of how you use it**. Do not spam or abuse it.
+
+<br/>
+
+## REST vs GraphQL
+
+The WXT Queue API is mostly a GraphQL API, with a few REST endpoints. This document covers all the REST endpoints, including the one used to make GraphQL requests.

src/assets/graphql-description.md

@@ -0,0 +1 @@
+To play around with the GraphQL API, checkout the [GraphiQL Playground](/playground).

src/routes/grpahql-routes.ts

@@ -15,16 +15,67 @@ export const graphqlRoutes = createApp()
   .post(
     "/api",
     {
-      body: z.object({
-        query: z.string(),
-        variables: z.record(z.string(), z.any()).optional(),
-        operationName: z.string().optional(),
-      }),
-      response: z.any(),
+      summary: "Send Query",
+      tags: ["GraphQL"],
+      description:
+        "Send a query to the GraphQL API. You can play around with queries on the [GraphiQL playground](/playground).",
+      body: z
+        .object({
+          query: z.string(),
+          variables: z.record(z.string(), z.any()).optional(),
+          operationName: z.string().optional(),
+        })
+        .meta({
+          example: {
+            query: `query GetExtension($id: String!) {
+  chromeExtension(id: $id) {
+    id
+    screenshots { rawUrl }
+  }
+}`,
+            variables: {
+              id: "ocfdgncpifmegplaglcnglhioflaimkd",
+            },
+            operationName: "GetExtension",
+          },
+        }),
+      response: z
+        .object({
+          data: z.any(),
+        })
+        .meta({
+          example: {
+            data: {
+              chromeExtension: {
+                id: "ocfdgncpifmegplaglcnglhioflaimkd",
+                screenshots: [
+                  {
+                    rawUrl:
+                      "https://lh3.googleusercontent.com/GUgh0ThX2FDPNvbaumYl4DqsUhsbYiCe-Hut9FoVEnkmTrXyA-sHbMk5jmZTj_t-dDP8rAmy6X6a6GNTCn9F8zo4VYU=s1280",
+                  },
+                  {
+                    rawUrl:
+                      "https://lh3.googleusercontent.com/qRi-kO0il8W6CnWa_-7oFzCwWKwr73w607I-rpYF9MM27omsuoN0k4dkgBbBECD3vZszdTSkQnoW9sywsfvAQ_7M9Q=s1280",
+                  },
+                ],
+              },
+            },
+          },
+        }),
     },
     ({ request, body }) => graphql.evaluateQuery(request.method, body),
   )
-  .get("/playground", ({ set }) => {
-    set.headers["Content-Type"] = "text/html; charset=utf-8";
-    return PLAYGROUND_HTML;
-  });
+  .get(
+    "/playground",
+    {
+      summary: "Playground",
+      tags: ["GraphQL"],
+      description:
+        "Open the GraphiQL playground. This is where you can interact and test out the GraphQL API. It also contains the GraphQL documentation explorer.",
+      response: z.string().meta({ contentType: "text/html" }),
+    },
+    ({ set }) => {
+      set.headers["Content-Type"] = "text/html; charset=utf-8";
+      return PLAYGROUND_HTML;
+    },
+  );

src/routes/rest-routes.ts

@@ -9,6 +9,10 @@ export const restRoutes = createApp()
   .get(
     "/api/rest/chrome-extensions/:id/screenshots/:index",
     {
+      summary: "Redirect to Screenshot",
+      tags: ["Chrome Extensions"],
+      description:
+        "Redirect to a screenshot's URL from the Chrome Web Store listing",
       params: z.object({
         id: z.string(),
         index: z.coerce.number().int().min(0),
@@ -29,6 +33,10 @@ export const restRoutes = createApp()
   .get(
     "/api/rest/firefox-addons/:addonId/screenshots/:index",
     {
+      summary: "Redirect to Screenshot",
+      tags: ["Firefox Addons"],
+      description:
+        "Redirect to a screenshot's URL from the Firefox Addons listing.",
       params: z.object({
         addonId: z.string(),
         index: z.coerce.number().int().min(0),

src/server.ts

@@ -5,14 +5,24 @@ import { graphqlRoutes } from "./routes/grpahql-routes";
 import { restRoutes } from "./routes/rest-routes";
 import { zodSchemaAdapter } from "@aklinker1/zeta/adapters/zod-schema-adapter";
 import { version } from "../package.json";
+import { z } from "zod/v4";
+import API_REFERENCE_DESCRIPTION from "./assets/api-reference-description.md" with { type: "text" };
+import GRAPHQL_DESCRIPTION from "./assets/graphql-description.md" with { type: "text" };
 
 const app = createApp({
   schemaAdapter: zodSchemaAdapter,
   openApi: {
     info: {
       title: "WXT Queue API Reference",
       version,
+      description: API_REFERENCE_DESCRIPTION,
     },
+    tags: [
+      { name: "GraphQL", description: GRAPHQL_DESCRIPTION },
+      { name: "Chrome Extensions" },
+      { name: "Firefox Addons" },
+      { name: "System" },
+    ],
   },
 })
   .onError(({ error }) => void consola.error(error))
@@ -21,11 +31,28 @@ const app = createApp({
   .use(graphqlRoutes)
   .get(
     "/",
-    { description: "Redirect to the GraphQL Playground" },
+    {
+      summary: "API Docs Redirect",
+      tags: ["System"],
+      description: "Redirect to the API reference when visiting the root URL.",
+    },
     ({ set }) => {
       set.status = 302;
-      set.headers.Location = "/playground";
+      set.headers.Location = "/scalar";
+    },
+  )
+  .get(
+    "/api/health",
+    {
+      summary: "Health Check",
+      tags: ["System"],
+      description: "Used to make sure the API is up and running.",
+      response: z.object({
+        status: z.literal("ok"),
+        version: z.string(),
+      }),
     },
+    () => ({ status: "ok" as const, version }),
   );
 
 export default app;