feat(sdk): improve method names (#82)

Author: matoous

README.md

@@ -107,7 +107,7 @@ CheckoutCreateRequest request =
         .returnUrl("https://example.com/webhook")
         .build();
 
-var checkout = client.checkouts().createCheckout(request);
+var checkout = client.checkouts().create(request);
 System.out.printf("Checkout %s created with id %s%n", checkout.checkoutReference(), checkout.id());
 ```
 
@@ -143,7 +143,7 @@ CompletableFuture<Void> checkoutFuture =
                       .returnUrl("https://example.com/webhook")
                       .build();
 
-              return client.checkouts().createCheckout(request);
+              return client.checkouts().create(request);
             })
         .thenAccept(
             checkout ->
@@ -175,7 +175,7 @@ String readerId =
     Optional.ofNullable(System.getenv("SUMUP_READER_ID"))
         .orElseGet(
             () ->
-                client.readers().listReaders(merchantCode).items().stream()
+                client.readers().list(merchantCode).items().stream()
                     .findFirst()
                     .map(reader -> reader.id().value())
                     .orElseThrow(() -> new IllegalStateException("No paired readers found.")));
@@ -192,7 +192,7 @@ CreateReaderCheckoutRequest request =
         .returnUrl("https://example.com/webhook")
         .build();
 
-client.readers().createReaderCheckout(merchantCode, readerId, request);
+client.readers().createCheckout(merchantCode, readerId, request);
 System.out.println("Reader checkout created.");
 ```
 
@@ -219,7 +219,7 @@ CompletableFuture<String> readerIdFuture =
             () ->
                 client
                     .readers()
-                    .listReaders(merchantCode)
+                    .list(merchantCode)
                     .thenApply(
                         response ->
                             response.items().stream()
@@ -244,7 +244,7 @@ readerIdFuture
                   .returnUrl("https://example.com/webhook")
                   .build();
 
-          return client.readers().createReaderCheckout(merchantCode, readerId, request);
+          return client.readers().createCheckout(merchantCode, readerId, request);
         })
     .thenAccept(
         response ->

codegen/internal/generator/method_name_test.go

@@ -0,0 +1,80 @@
+package generator
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestGenerateClientUsesCodegenMethodName(t *testing.T) {
+	t.Parallel()
+
+	tmp := t.TempDir()
+	specPath := filepath.Join(tmp, "openapi.json")
+	outputDir := filepath.Join(tmp, "src", "main", "java")
+	resourceDir := filepath.Join(tmp, "src", "main", "resources")
+
+	spec := `{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "test",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/v0.1/merchants/{merchant_code}/readers/{reader_id}/terminate": {
+      "post": {
+        "operationId": "CreateReaderTerminate",
+        "summary": "Terminate a Reader Checkout",
+        "parameters": [
+          {
+            "name": "merchant_code",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          },
+          {
+            "name": "reader_id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Terminated"
+          }
+        },
+        "tags": ["Readers"],
+        "x-codegen": {
+          "method_name": "terminate_checkout"
+        }
+      }
+    }
+  }
+}`
+	if err := os.WriteFile(specPath, []byte(spec), 0o644); err != nil {
+		t.Fatalf("write spec: %v", err)
+	}
+
+	params := Params{
+		SpecPath:    specPath,
+		OutputDir:   outputDir,
+		ResourceDir: resourceDir,
+		BasePackage: "com.test.sdk",
+	}
+	if err := Run(context.Background(), params); err != nil {
+		t.Fatalf("run generator: %v", err)
+	}
+
+	clientPath := filepath.Join(outputDir, "com", "test", "sdk", "clients", "ReadersClient.java")
+	content, err := os.ReadFile(clientPath)
+	if err != nil {
+		t.Fatalf("read generated client: %v", err)
+	}
+	generated := string(content)
+
+	assertContains(t, generated, "void terminateCheckout(String merchantCode, String readerId)")
+	assertContains(t, generated, "Operation ID: CreateReaderTerminate")
+	assertNotContains(t, generated, "createReaderTerminate")
+}

codegen/internal/generator/model.go

@@ -233,7 +233,7 @@ func convertOperation(method, path string, item *v3.PathItem, op *v3.Operation,
 	sanitizedID := sanitizeOperationID(op.OperationId)
 	model := operationModel{
 		OperationID:      sanitizedID,
-		MethodName:       camelCase(sanitizedID, "operation"),
+		MethodName:       operationMethodName(op, sanitizedID),
 		SummaryLines:     splitComment(strings.TrimSpace(op.Summary)),
 		DescriptionLines: splitComment(strings.TrimSpace(op.Description)),
 		HttpMethod:       strings.ToUpper(method),
@@ -306,6 +306,33 @@ func sanitizeOperationID(operationID string) string {
 	return operationID
 }
 
+// operationMethodName returns the Java method name for an OpenAPI operation.
+// When present, x-codegen.method_name is preferred because generated methods
+// are already scoped to their tag client.
+func operationMethodName(op *v3.Operation, fallbackID string) string {
+	if methodName := codegenMethodName(op); methodName != "" {
+		return camelCase(methodName, "operation")
+	}
+	return camelCase(fallbackID, "operation")
+}
+
+func codegenMethodName(op *v3.Operation) string {
+	if op == nil || op.Extensions == nil {
+		return ""
+	}
+	node := op.Extensions.GetOrZero("x-codegen")
+	if node == nil {
+		return ""
+	}
+	var extension struct {
+		MethodName string `yaml:"method_name"`
+	}
+	if err := node.Decode(&extension); err != nil {
+		return ""
+	}
+	return strings.TrimSpace(extension.MethodName)
+}
+
 // collectParameters merges operation and path-level parameters, filtering out
 // nil references along the way.
 func collectParameters(item *v3.PathItem, op *v3.Operation) []*v3.Parameter {

examples/basic/src/main/java/com/sumup/examples/basic/BasicExample.java

@@ -18,7 +18,7 @@ public static void main(String[] args) {
     SumUpClient client = new SumUpClient();
 
     try {
-      List<com.sumup.sdk.models.CheckoutSuccess> checkouts = client.checkouts().listCheckouts();
+      List<com.sumup.sdk.models.CheckoutSuccess> checkouts = client.checkouts().list();
       System.out.printf("Fetched %d checkouts.%n", checkouts.size());
     } catch (ApiException ex) {
       System.err.printf(

examples/card-reader-checkout/src/main/java/com/sumup/examples/cardreader/CardReaderCheckoutExample.java

@@ -18,7 +18,7 @@ public static void main(String[] args) {
     SumUpClient client = new SumUpClient();
 
     Optional<String> readerId =
-        client.readers().listReaders(merchantCode).items().stream()
+        client.readers().list(merchantCode).items().stream()
             .findFirst()
             .map(reader -> reader.id().value());
     if (readerId.isEmpty()) {
@@ -46,7 +46,7 @@ private static boolean createReaderCheckout(
             .build();
 
     try {
-      client.readers().createReaderCheckout(merchantCode, readerId, request);
+      client.readers().createCheckout(merchantCode, readerId, request);
       return true;
     } catch (ApiException ex) {
       System.err.printf(