Improve API docs with examples, CORS, and move to /api

- Move API docs from /api-docs to /api for cleaner URL
- Add CORS headers and X-Execution-Time to /api/jq responses
- Add OpenAPI examples for all endpoints so users can test immediately
- Add query params schema for GET /api/jq
- Add path params schema for GET /api/snippets/{slug}
- Create post-processing script to inject examples after generation

Author: owenthereal

next.openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "jq Playground API",
     "version": "1.0.0",
-    "description": "Execute jq queries and share snippets"
+    "description": "Execute jq queries and share snippets.\n\n**Want a UI?** Try the [jq playground](https://play.jqlang.org) for an interactive experience."
   },
   "servers": [
     {

package.json

@@ -13,7 +13,7 @@
     "copy-monaco": "bash scripts/copy-monaco.sh",
     "setup-db": "node scripts/setup-db.js",
     "prisma:migrate": "npm run setup-db && npx prisma migrate dev",
-    "openapi": "next-openapi-gen generate"
+    "openapi": "next-openapi-gen generate && node scripts/add-openapi-examples.js"
   },
   "dependencies": {
     "@emotion/react": "^11.14.0",

public/openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "jq Playground API",
     "version": "1.0.0",
-    "description": "Execute jq queries and share snippets"
+    "description": "Execute jq queries and share snippets.\n\n**Want a UI?** Try the [jq playground](https://play.jqlang.org) for an interactive experience."
   },
   "servers": [
     {
@@ -32,6 +32,31 @@
           "status"
         ]
       },
+      "JqQueryParamsSchema": {
+        "type": "object",
+        "properties": {
+          "json": {
+            "type": "string",
+            "description": "JSON input to process",
+            "example": "{\"name\": \"jq\", \"version\": \"1.7\"}"
+          },
+          "query": {
+            "type": "string",
+            "description": "jq query to execute",
+            "example": ".name"
+          },
+          "options": {
+            "type": "string",
+            "nullable": true,
+            "description": "Comma-separated jq options (e.g., \"-r,-c\")",
+            "example": "-r,-c"
+          }
+        },
+        "required": [
+          "json",
+          "query"
+        ]
+      },
       "JqResponseSchema": {
         "type": "object",
         "properties": {
@@ -49,28 +74,43 @@
         "properties": {
           "json": {
             "type": "string",
-            "description": "JSON input to process"
+            "description": "JSON input to process",
+            "example": "{\"name\": \"jq\", \"version\": \"1.7\"}"
           },
           "query": {
             "type": "string",
-            "description": "jq query to execute"
+            "description": "jq query to execute",
+            "example": ".name"
           },
           "options": {
             "allOf": [
               {
                 "$ref": "#/components/schemas/Options"
               }
             ],
-            "description": "jq command-line options"
+            "description": "jq command-line options",
+            "example": [
+              "-r",
+              "-c"
+            ]
           }
         },
         "required": [
           "json",
           "query"
         ]
       },
-      "slug": {
-        "type": "object"
+      "SnippetPathParamsSchema": {
+        "type": "object",
+        "properties": {
+          "slug": {
+            "type": "string",
+            "description": "Unique snippet identifier"
+          }
+        },
+        "required": [
+          "slug"
+        ]
       },
       "Snippet": {
         "type": "object",
@@ -401,11 +441,45 @@
       "get": {
         "operationId": "get-jq",
         "summary": "Execute a jq query via query parameters",
-        "description": "Execute a jq query against JSON input via query parameters",
+        "description": "Execute a jq query against JSON input via query parameters. Great for simple queries and quick testing.",
         "tags": [
           "Jq"
         ],
-        "parameters": [],
+        "parameters": [
+          {
+            "in": "query",
+            "name": "json",
+            "schema": {
+              "type": "string",
+              "description": "JSON input to process",
+              "example": "{\"name\": \"jq\", \"version\": \"1.7\"}"
+            },
+            "required": false,
+            "description": "JSON input to process"
+          },
+          {
+            "in": "query",
+            "name": "query",
+            "schema": {
+              "type": "string",
+              "description": "jq query to execute",
+              "example": ".name"
+            },
+            "required": false,
+            "description": "jq query to execute"
+          },
+          {
+            "in": "query",
+            "name": "options",
+            "schema": {
+              "type": "string",
+              "description": "Comma-separated jq options (e.g., \"-r,-c\")",
+              "example": "-r,-c"
+            },
+            "required": false,
+            "description": "Comma-separated jq options (e.g., \"-r,-c\")"
+          }
+        ],
         "responses": {
           "200": {
             "description": "Successful response",
@@ -428,7 +502,7 @@
       "post": {
         "operationId": "post-jq",
         "summary": "Execute a jq query",
-        "description": "Execute a jq query against JSON input",
+        "description": "Execute a jq query against JSON input. Use this for complex queries or large JSON payloads.",
         "tags": [
           "Jq"
         ],
@@ -476,6 +550,13 @@
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/Snippet"
+              },
+              "example": {
+                "json": "{\"name\": \"jq\", \"version\": \"1.7\"}",
+                "query": ".name",
+                "options": [
+                  "-r"
+                ]
               }
             }
           }
@@ -508,7 +589,19 @@
         "tags": [
           "Snippets"
         ],
-        "parameters": [],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "slug",
+            "schema": {
+              "type": "string",
+              "description": "Unique snippet identifier"
+            },
+            "required": true,
+            "description": "Unique snippet identifier",
+            "example": "slug"
+          }
+        ],
         "responses": {
           "200": {
             "description": "Successful response",
@@ -530,4 +623,4 @@
       }
     }
   }
-}
+}

scripts/add-openapi-examples.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Post-process the generated OpenAPI spec to add examples for jq API parameters.
+ * Run this after `next-openapi-gen generate`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const OPENAPI_PATH = path.join(__dirname, '../public/openapi.json');
+
+// Example values that users can run immediately
+const GET_EXAMPLES = {
+  json: '{"name": "jq", "version": "1.7"}',
+  query: '.name',
+  options: '-r,-c', // comma-separated string for query params
+};
+
+const POST_EXAMPLES = {
+  json: '{"name": "jq", "version": "1.7"}',
+  query: '.name',
+  options: ['-r', '-c'], // array for request body
+};
+
+function addExamples() {
+  const spec = JSON.parse(fs.readFileSync(OPENAPI_PATH, 'utf8'));
+
+  // Add examples to GET /jq query parameters
+  const jqGetPath = spec.paths?.['/jq']?.get;
+  if (jqGetPath?.parameters) {
+    for (const param of jqGetPath.parameters) {
+      if (param.name && GET_EXAMPLES[param.name]) {
+        param.schema = param.schema || {};
+        param.schema.example = GET_EXAMPLES[param.name];
+      }
+    }
+  }
+
+  // Add examples to POST /jq request body schema
+  const jqPostPath = spec.paths?.['/jq']?.post;
+  const postBodySchema = jqPostPath?.requestBody?.content?.['application/json']?.schema;
+  if (postBodySchema) {
+    // Handle $ref - need to update the component schema directly
+    if (postBodySchema.$ref) {
+      const schemaName = postBodySchema.$ref.split('/').pop();
+      const componentSchema = spec.components?.schemas?.[schemaName];
+      if (componentSchema?.properties) {
+        addExamplesToProperties(componentSchema.properties, POST_EXAMPLES);
+      }
+    } else if (postBodySchema.properties) {
+      addExamplesToProperties(postBodySchema.properties, POST_EXAMPLES);
+    }
+  }
+
+  // Also update the JqQueryParamsSchema if it exists in components
+  const queryParamsSchema = spec.components?.schemas?.JqQueryParamsSchema;
+  if (queryParamsSchema?.properties) {
+    addExamplesToProperties(queryParamsSchema.properties, GET_EXAMPLES);
+  }
+
+  // Add example to POST /snippets request body (exclude http field)
+  const snippetsPostPath = spec.paths?.['/snippets']?.post;
+  const snippetsBodyContent = snippetsPostPath?.requestBody?.content?.['application/json'];
+  if (snippetsBodyContent) {
+    snippetsBodyContent.example = {
+      json: '{"name": "jq", "version": "1.7"}',
+      query: '.name',
+      options: ['-r'],
+    };
+  }
+
+  fs.writeFileSync(OPENAPI_PATH, JSON.stringify(spec, null, 2) + '\n');
+  console.log('Added examples to OpenAPI spec');
+}
+
+function addExamplesToProperties(properties, examples) {
+  for (const [name, prop] of Object.entries(properties)) {
+    if (examples[name] && !prop.example) {
+      prop.example = examples[name];
+    }
+  }
+}
+
+addExamples();

src/app/api/jq/route.ts

@@ -1,12 +1,21 @@
 import { ZodError } from 'zod';
 import * as Sentry from '@sentry/nextjs';
-import { JqRequestSchema, JqResponse, JqError } from '@/schemas/api';
+import { JqRequestSchema, JqQueryParamsSchema, JqResponse, JqError } from '@/schemas/api';
 import { runJqWithTimeout, TimeoutError } from '@/workers/server';
 
 const TIMEOUT_MS = 5000; // 5 seconds
 
-function jsonResponse<T>(data: T, status: number): Response {
-    return Response.json(data, { status });
+const CORS_HEADERS = {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type',
+};
+
+function jsonResponse<T>(data: T, status: number, headers?: Record<string, string>): Response {
+    return Response.json(data, {
+        status,
+        headers: { ...CORS_HEADERS, ...headers },
+    });
 }
 
 function handleError(e: unknown): Response {
@@ -31,9 +40,20 @@ function handleError(e: unknown): Response {
     return jsonResponse(error, 500);
 }
 
+/**
+ * Handle CORS preflight requests
+ */
+export async function OPTIONS() {
+    return new Response(null, {
+        status: 204,
+        headers: CORS_HEADERS,
+    });
+}
+
 /**
  * Execute a jq query via query parameters
- * @description Execute a jq query against JSON input via query parameters
+ * @description Execute a jq query against JSON input via query parameters. Great for simple queries and quick testing.
+ * @params JqQueryParamsSchema
  * @response 200:JqResponseSchema
  * @response 400:JqErrorSchema
  * @response 408:JqErrorSchema
@@ -59,23 +79,27 @@ export async function GET(request: Request) {
 
         const validated = JqRequestSchema.parse({ json, query, options });
 
+        const startTime = performance.now();
         const result = await runJqWithTimeout(
             validated.json,
             validated.query,
             validated.options ?? undefined,
             TIMEOUT_MS
         );
+        const executionTime = Math.round(performance.now() - startTime);
 
         const response: JqResponse = { result };
-        return jsonResponse(response, 200);
+        return jsonResponse(response, 200, {
+            'X-Execution-Time': `${executionTime}ms`,
+        });
     } catch (e: unknown) {
         return handleError(e);
     }
 }
 
 /**
  * Execute a jq query
- * @description Execute a jq query against JSON input
+ * @description Execute a jq query against JSON input. Use this for complex queries or large JSON payloads.
  * @body JqRequestSchema
  * @response 200:JqResponseSchema
  * @response 400:JqErrorSchema
@@ -88,15 +112,19 @@ export async function POST(request: Request) {
         const body = await request.json();
         const { json, query, options } = JqRequestSchema.parse(body);
 
+        const startTime = performance.now();
         const result = await runJqWithTimeout(
             json,
             query,
             options ?? undefined,
             TIMEOUT_MS
         );
+        const executionTime = Math.round(performance.now() - startTime);
 
         const response: JqResponse = { result };
-        return jsonResponse(response, 200);
+        return jsonResponse(response, 200, {
+            'X-Execution-Time': `${executionTime}ms`,
+        });
     } catch (e: unknown) {
         return handleError(e);
     }