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.mdnew file mode 100644index 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.gonew file mode 100644index 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.shnew file mode 100755index 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 ""