Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

tools: add API documentation generation scripts - Go AST parser and bash script

Mario09abbccd9f61
diff --git a/scripts/API_DOCS_GENERATION.md b/scripts/API_DOCS_GENERATION.md
new file mode 100644
index 00000000..7200bcc5
--- /dev/null
+++ b/scripts/API_DOCS_GENERATION.md
@@ -0,0 +1,120 @@
+# Generating API Documentation
+
+This guide explains how to automatically generate API reference documentation from Go code.
+
+## Overview
+
+We have two tools to help generate API documentation:
+
+1. **Go tool** (`scripts/gen-api-docs/main.go`) — More reliable, parses Go AST
+2. **Bash script** (`scripts/generate-api-docs.sh`) — Simple pattern matching
+
+## Using the Go Tool (Recommended)
+
+### Generate Endpoint Summary
+
+```bash
+# Run from repo root
+go run scripts/gen-api-docs/main.go
+```
+
+**Output:**
+- Endpoint summary table (Method, Path, Handler)
+- Detailed endpoint list
+- Handler names
+
+### Redirect to File
+
+```bash
+go run scripts/gen-api-docs/main.go > docs/references/endpoints-auto.md
+```
+
+### What It Extracts
+
+- HTTP method (GET, POST, PUT, DELETE, PATCH)
+- Path pattern (e.g., `/snapshot`, `/action`)
+- Handler function name (e.g., `HandleSnapshot`)
+- Sorts by method, then path
+
+## How It Works
+
+The Go tool:
+
+1. **Parses** `internal/handlers/handlers.go`
+2. **Uses Go AST** to find `RegisterRoutes()` function
+3. **Extracts** all `mux.HandleFunc()` and `mux.Handle()` calls
+4. **Parses** route strings with pattern: `"METHOD /path"`
+5. **Generates** markdown documentation
+
+### Limitations
+
+Currently extracts:
+- ✅ HTTP method and path
+- ✅ Handler function name
+- ❌ Query parameters (would need to parse handler functions)
+- ❌ Request body structure (would need struct tag analysis)
+- ❌ Response types (would need return type analysis)
+
+## Enhancing the Tool
+
+To add more features, extend `scripts/gen-api-docs/main.go`:
+
+### Extract Query Parameters
+
+```go
+// Look for r.URL.Query().Get("paramName") in handler code
+// Parse parameters from handler functions
+```
+
+### Extract Request Body Structure
+
+```go
+// Look for json.Unmarshal patterns
+// Parse request struct definitions
+// Extract field names and types
+```
+
+### Extract Response Types
+
+```go
+// Analyze handler return types
+// Look for json.Marshal patterns
+// Extract response struct definitions
+```
+
+## Current Usage
+
+The manually-written `docs/references/endpoints.md` is the source of truth because it includes:
+- Full request/response examples
+- Query parameters and defaults
+- Error responses
+- Usage examples
+
+**Auto-generation tool is useful for:**
+- Verifying endpoints are documented
+- Creating a quick reference table
+- Tracking which endpoints exist in code
+- Finding undocumented endpoints
+
+## Next Steps
+
+To make this fully automated:
+
+1. Add structured comments above handler functions:
+ ```go
+ // HandleSnapshot returns the accessibility tree
+ // Query params: tabId, filter, interactive
+ func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {
+ ```
+
+2. Use the `go/parser` with structured comments to extract documentation
+
+3. Parse request/response types using `go/types` for full type information
+
+4. Generate complete API docs automatically (with parameter docs, types, examples)
+
+## Related Files
+
+- `internal/handlers/handlers.go` — Route definitions
+- `internal/handlers/*.go` — Handler implementations
+- `docs/references/endpoints.md` — Manually-written API docs (source of truth)
diff --git a/scripts/gen-api-docs/main.go b/scripts/gen-api-docs/main.go
new file mode 100644
index 00000000..214ae43e
--- /dev/null
+++ b/scripts/gen-api-docs/main.go
@@ -0,0 +1,172 @@
+package main
+
+import (
+ "fmt"
+ "go/ast"
+ "go/parser"
+ "go/token"
+ "log"
+ "regexp"
+ "sort"
+ "strings"
+ "time"
+)
+
+type Endpoint struct {
+ Method string
+ Path string
+ Handler string
+ Doc string
+}
+
+func main() {
+ // Parse handlers.go to extract routes
+ endpoints := extractEndpoints("internal/handlers/handlers.go")
+
+ // Sort by method then path
+ sort.Slice(endpoints, func(i, j int) bool {
+ if endpoints[i].Method != endpoints[j].Method {
+ return endpoints[i].Method < endpoints[j].Method
+ }
+ return endpoints[i].Path < endpoints[j].Path
+ })
+
+ // Generate markdown
+ fmt.Println("# API Reference (Auto-Generated)")
+ fmt.Println("")
+ fmt.Printf("Generated: %s\n", time.Now().UTC().Format(time.RFC3339))
+ fmt.Println("")
+ fmt.Println("---")
+ fmt.Println("")
+
+ fmt.Println("## Endpoints Summary")
+ fmt.Println("")
+ fmt.Println("| Method | Path | Handler | Notes |")
+ fmt.Println("|--------|------|---------|-------|")
+
+ for _, ep := range endpoints {
+ notes := ""
+ if ep.Doc != "" {
+ notes = strings.TrimSpace(ep.Doc)
+ if len(notes) > 50 {
+ notes = notes[:50] + "..."
+ }
+ }
+ fmt.Printf("| %s | `%s` | %s | %s |\n", ep.Method, ep.Path, ep.Handler, notes)
+ }
+
+ fmt.Println("")
+ fmt.Println("---")
+ fmt.Println("")
+ fmt.Println("## Detailed Endpoints")
+ fmt.Println("")
+
+ for _, ep := range endpoints {
+ fmt.Printf("### %s %s\n", ep.Method, ep.Path)
+ fmt.Println("")
+
+ if ep.Doc != "" {
+ fmt.Printf("%s\n", ep.Doc)
+ fmt.Println("")
+ }
+
+ fmt.Printf("**Handler:** `%s`\n", ep.Handler)
+ fmt.Println("")
+ }
+
+ fmt.Println("---")
+ fmt.Println("")
+ fmt.Println("## Notes")
+ fmt.Println("")
+ fmt.Println("- This documentation is auto-generated from Go code")
+ fmt.Println("- For full implementation details, see `internal/handlers/*.go`")
+ fmt.Println("- Query parameters and request bodies are defined in each handler")
+ fmt.Println("")
+}
+
+func extractEndpoints(filePath string) []Endpoint {
+ fset := token.NewFileSet()
+ file, err := parser.ParseFile(fset, filePath, nil, parser.ParseComments)
+ if err != nil {
+ log.Fatalf("Error parsing file: %v", err)
+ }
+
+ var endpoints []Endpoint
+
+ // Find RegisterRoutes function
+ for _, decl := range file.Decls {
+ funcDecl, ok := decl.(*ast.FuncDecl)
+ if !ok || funcDecl.Name.Name != "RegisterRoutes" {
+ continue
+ }
+
+ // Extract HandleFunc calls
+ endpoints = extractHandleFuncCalls(funcDecl.Body)
+ }
+
+ return endpoints
+}
+
+func extractHandleFuncCalls(body *ast.BlockStmt) []Endpoint {
+ var endpoints []Endpoint
+
+ routePattern := regexp.MustCompile(`^(GET|POST|PUT|DELETE|PATCH)\s+(/[^\s]*)`)
+
+ for _, stmt := range body.List {
+ exprStmt, ok := stmt.(*ast.ExprStmt)
+ if !ok {
+ continue
+ }
+
+ callExpr, ok := exprStmt.X.(*ast.CallExpr)
+ if !ok {
+ continue
+ }
+
+ // Check if this is mux.HandleFunc or mux.Handle
+ selector, ok := callExpr.Fun.(*ast.SelectorExpr)
+ if !ok {
+ continue
+ }
+
+ if selector.Sel.Name != "HandleFunc" && selector.Sel.Name != "Handle" {
+ continue
+ }
+
+ // Extract route pattern (first argument)
+ if len(callExpr.Args) < 1 {
+ continue
+ }
+
+ basicLit, ok := callExpr.Args[0].(*ast.BasicLit)
+ if !ok {
+ continue
+ }
+
+ // Parse route string
+ route := strings.Trim(basicLit.Value, "\"")
+ matches := routePattern.FindStringSubmatch(route)
+ if len(matches) < 3 {
+ continue
+ }
+
+ method := matches[1]
+ path := matches[2]
+
+ // Extract handler name (second argument)
+ var handler string
+ if len(callExpr.Args) >= 2 {
+ if selectorExpr, ok := callExpr.Args[1].(*ast.SelectorExpr); ok {
+ handler = selectorExpr.Sel.Name
+ }
+ }
+
+ endpoints = append(endpoints, Endpoint{
+ Method: method,
+ Path: path,
+ Handler: handler,
+ })
+ }
+
+ return endpoints
+}
diff --git a/scripts/generate-api-docs.sh b/scripts/generate-api-docs.sh
new file mode 100755
index 00000000..ca27ebb6
--- /dev/null
+++ b/scripts/generate-api-docs.sh
@@ -0,0 +1,68 @@
+#!/bin/bash
+# Generate API reference documentation from Go handler definitions
+# Usage: ./scripts/generate-api-docs.sh > docs/references/endpoints-generated.md
+
+set -e
+
+cd "$(dirname "$0")/.."
+
+echo "# API Reference (Auto-Generated)"
+echo ""
+echo "This documentation is generated from Go code."
+echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+echo ""
+echo "---"
+echo ""
+
+echo "## Endpoints Summary"
+echo ""
+echo "| Method | Path | Handler |"
+echo "|--------|------|---------|"
+
+# Extract routes from handlers.go
+grep -E 'mux\.Handle(Func)?\(' internal/handlers/handlers.go | \
+ sed -E 's/.*mux\.HandleFunc?\("([A-Z]+) ([^"]+)".*h\.([A-Za-z]+).*/| \1 | \2 | \3 |/' | \
+ sort
+
+echo ""
+echo "---"
+echo ""
+echo "## Detailed Endpoints"
+echo ""
+
+# Extract each route and try to find documentation
+while IFS= read -r line; do
+ if [[ $line =~ mux\.HandleFunc\(\"([A-Z]+)[[:space:]]+([^\"]+)\".*h\.([A-Za-z0-9]+) ]]; then
+ METHOD="${BASH_REMATCH[1]}"
+ PATH="${BASH_REMATCH[2]}"
+ HANDLER="${BASH_REMATCH[3]}"
+
+ # Find the handler in the codebase
+ HANDLER_FILE=$(grep -l "func.*($HANDLER" internal/handlers/*.go 2>/dev/null | head -1)
+
+ if [ -n "$HANDLER_FILE" ]; then
+ # Extract comments before the handler
+ COMMENT=$(grep -B 5 "func.*($HANDLER" "$HANDLER_FILE" | grep "^[[:space:]]*\/\/" | head -1 | sed 's/^[[:space:]]*\/\/[[:space:]]*//')
+
+ echo "### $METHOD $PATH"
+ echo ""
+ if [ -n "$COMMENT" ]; then
+ echo "$COMMENT"
+ echo ""
+ fi
+ echo "\`\`\`"
+ echo "$METHOD $PATH"
+ echo "\`\`\`"
+ echo ""
+ fi
+ fi
+done < <(grep 'mux\.HandleFunc' internal/handlers/handlers.go | head -20)
+
+echo "---"
+echo ""
+echo "## Notes"
+echo ""
+echo "- This documentation is auto-generated from Go code"
+echo "- For full details, see inline comments in \`internal/handlers/*.go\`"
+echo "- Query parameters and request bodies vary by endpoint"
+echo ""