From a469a78b2acf9d1f2dd8aa97742d7c6586e50ab7 Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Thu, 2 Apr 2026 03:25:25 +0000
Subject: [PATCH] feat(openapi): document GraphQL GET queries

Co-Authored-By: Virgil <virgil@lethean.io>
---
 openapi.go      | 45 +++++++++++++++++++++++++++++++++++++++++++++
 openapi_test.go | 15 +++++++++++++++
 2 files changed, 60 insertions(+)

diff --git a/openapi.go b/openapi.go
index a08b8fb..0f6ce2b 100644
--- a/openapi.go
+++ b/openapi.go
@@ -702,6 +702,19 @@ func sortTags(tags []map[string]any) {
 
 func graphqlPathItem(path string, operationIDs map[string]int) map[string]any {
 	return map[string]any{
+		"get": map[string]any{
+			"summary":     "GraphQL query",
+			"description": "Executes GraphQL queries over GET using query parameters",
+			"tags":        []string{"graphql"},
+			"operationId": operationID("get", path, operationIDs),
+			"security": []any{
+				map[string]any{
+					"bearerAuth": []any{},
+				},
+			},
+			"parameters": graphqlQueryParameters(),
+			"responses":  graphqlResponses(),
+		},
 		"post": map[string]any{
 			"summary":     "GraphQL query",
 			"description": "Executes GraphQL queries and mutations",
@@ -1012,6 +1025,38 @@ func graphqlRequestSchema() map[string]any {
 	}
 }
 
+func graphqlQueryParameters() []map[string]any {
+	return []map[string]any{
+		{
+			"name":        "query",
+			"in":          "query",
+			"required":    true,
+			"description": "GraphQL query or mutation document",
+			"schema": map[string]any{
+				"type": "string",
+			},
+		},
+		{
+			"name":        "variables",
+			"in":          "query",
+			"required":    false,
+			"description": "JSON-encoded GraphQL variables",
+			"schema": map[string]any{
+				"type": "string",
+			},
+		},
+		{
+			"name":        "operationName",
+			"in":          "query",
+			"required":    false,
+			"description": "Operation name to execute",
+			"schema": map[string]any{
+				"type": "string",
+			},
+		},
+	}
+}
+
 func graphqlResponses() map[string]any {
 	successHeaders := mergeHeaders(standardResponseHeaders(), rateLimitSuccessHeaders(), cacheSuccessHeaders())
 	errorHeaders := mergeHeaders(standardResponseHeaders(), rateLimitSuccessHeaders())
diff --git a/openapi_test.go b/openapi_test.go
index 3592ae0..3d6e43e 100644
--- a/openapi_test.go
+++ b/openapi_test.go
@@ -268,6 +268,21 @@ func TestSpecBuilder_Good_GraphQLEndpoint(t *testing.T) {
 		t.Fatal("expected /graphql path in spec")
 	}
 
+	getOp := pathItem["get"].(map[string]any)
+	if getOp["operationId"] != "get_graphql" {
+		t.Fatalf("expected GraphQL GET operationId to be get_graphql, got %v", getOp["operationId"])
+	}
+	getParams := getOp["parameters"].([]any)
+	if len(getParams) != 3 {
+		t.Fatalf("expected 3 GraphQL GET query parameters, got %d", len(getParams))
+	}
+	if getParams[0].(map[string]any)["name"] != "query" {
+		t.Fatalf("expected first GraphQL GET parameter to be query, got %v", getParams[0])
+	}
+	if getParams[0].(map[string]any)["required"] != true {
+		t.Fatal("expected GraphQL GET query parameter to be required")
+	}
+
 	postOp := pathItem["post"].(map[string]any)
 	if postOp["operationId"] != "post_graphql" {
 		t.Fatalf("expected GraphQL operationId to be post_graphql, got %v", postOp["operationId"])