sumup · matoous · Apr 8, 2026 · Apr 8, 2026
diff --git a/codegen/internal/generator/model.go b/codegen/internal/generator/model.go
@@ -22,6 +22,7 @@ type sdkModel struct {
 // clientModel encapsulates the data necessary to render a Java API client.
 type clientModel struct {
 	TagName      string
+	TagDescriptionLines []string
 	ClassName    string
 	AccessorName string
 	FieldName    string
@@ -128,6 +129,15 @@ const (
 // used by renderers to generate source files.
 func buildModel(doc *v3.Document, params Params) (sdkModel, error) {
 	resolver := newTypeResolver(doc, params)
+	tagDescriptions := map[string][]string{}
+	if doc.Tags != nil {
+		for _, tag := range doc.Tags {
+			if tag == nil {
+				continue
+			}
+			tagDescriptions[firstTag([]string{tag.Name})] = splitComment(strings.TrimSpace(tag.Description))
+		}
+	}
 	groups := map[string][]operationModel{}
 	if doc.Paths != nil && doc.Paths.PathItems != nil && doc.Paths.PathItems.Len() > 0 {
 		for path, item := range doc.Paths.PathItems.FromOldest() {
@@ -181,12 +191,13 @@ func buildModel(doc *v3.Document, params Params) (sdkModel, error) {
 		}
 
 		clients = append(clients, clientModel{
-			TagName:      tag,
-			ClassName:    className,
-			AccessorName: accessor,
-			FieldName:    fieldName,
-			Package:      params.clientPackage(),
-			Methods:      ops,
+			TagName:             tag,
+			TagDescriptionLines: tagDescriptions[tag],
+			ClassName:           className,
+			AccessorName:        accessor,
+			FieldName:           fieldName,
+			Package:             params.clientPackage(),
+			Methods:             ops,
 		})
 	}
 

diff --git a/codegen/internal/generator/render.go b/codegen/internal/generator/render.go
@@ -168,6 +168,7 @@ type clientTemplateData struct {
 	Package       string
 	ClassName     string
 	TagName       string
+	TagDescriptionLines []string
 	Imports       []string
 	Operations    []operationTemplateData
 	QueryStructs  []*parameterGroupModel
@@ -320,13 +321,14 @@ func prepareClientTemplateData(client clientModel, className string, async bool)
 	sort.Strings(imports)
 
 	return clientTemplateData{
-		Package:       client.Package,
-		ClassName:     className,
-		TagName:       client.TagName,
-		Imports:       imports,
-		Operations:    operations,
-		QueryStructs:  queryStructs,
-		HeaderStructs: headerStructs,
+		Package:             client.Package,
+		ClassName:           className,
+		TagName:             client.TagName,
+		TagDescriptionLines: client.TagDescriptionLines,
+		Imports:             imports,
+		Operations:          operations,
+		QueryStructs:        queryStructs,
+		HeaderStructs:       headerStructs,
 	}
 }
 

diff --git a/codegen/internal/generator/templates/client.tmpl b/codegen/internal/generator/templates/client.tmpl
@@ -6,6 +6,12 @@ import {{ . }};
 
 /**
  * Client for the "{{ .TagName }}" API group.
+{{- if .TagDescriptionLines }}
+ *
+{{- range .TagDescriptionLines }}
+ * {{ . }}
+{{- end }}
+{{- end }}
  */
 public final class {{ .ClassName }} {
     private final ApiClient apiClient;

diff --git a/codegen/internal/generator/templates/client_async.tmpl b/codegen/internal/generator/templates/client_async.tmpl
@@ -6,6 +6,12 @@ import {{ . }};
 
 /**
  * Client for the "{{ .TagName }}" API group.
+{{- if .TagDescriptionLines }}
+ *
+{{- range .TagDescriptionLines }}
+ * {{ . }}
+{{- end }}
+{{- end }}
  */
 public final class {{ .ClassName }} {
     private final ApiClient apiClient;

diff --git a/codegen/internal/generator/templates/sumup_client.tmpl b/codegen/internal/generator/templates/sumup_client.tmpl
@@ -70,7 +70,7 @@ public final class {{ .ClassName }} {
 
 {{- range .Clients }}
     /**
-     * Returns the {{ .ClassName }} client exposing endpoints tagged with "{{ .TagName }}".
+     * Returns the {{ .ClassName }} client for the "{{ .TagName }}" API group.
      *
      * @return Client for the associated API group.
      */

diff --git a/src/main/java/com/sumup/sdk/SumUpAsyncClient.java b/src/main/java/com/sumup/sdk/SumUpAsyncClient.java
@@ -96,7 +96,7 @@ public ApiClient apiClient() {
   }
 
   /**
-   * Returns the CheckoutsAsyncClient client exposing endpoints tagged with "Checkouts".
+   * Returns the CheckoutsAsyncClient client for the "Checkouts" API group.
    *
    * @return Client for the associated API group.
    */
@@ -105,7 +105,7 @@ public CheckoutsAsyncClient checkouts() {
   }
 
   /**
-   * Returns the CustomersAsyncClient client exposing endpoints tagged with "Customers".
+   * Returns the CustomersAsyncClient client for the "Customers" API group.
    *
    * @return Client for the associated API group.
    */
@@ -114,7 +114,7 @@ public CustomersAsyncClient customers() {
   }
 
   /**
-   * Returns the MembersAsyncClient client exposing endpoints tagged with "Members".
+   * Returns the MembersAsyncClient client for the "Members" API group.
    *
    * @return Client for the associated API group.
    */
@@ -123,7 +123,7 @@ public MembersAsyncClient members() {
   }
 
   /**
-   * Returns the MembershipsAsyncClient client exposing endpoints tagged with "Memberships".
+   * Returns the MembershipsAsyncClient client for the "Memberships" API group.
    *
    * @return Client for the associated API group.
    */
@@ -132,7 +132,7 @@ public MembershipsAsyncClient memberships() {
   }
 
   /**
-   * Returns the MerchantsAsyncClient client exposing endpoints tagged with "Merchants".
+   * Returns the MerchantsAsyncClient client for the "Merchants" API group.
    *
    * @return Client for the associated API group.
    */
@@ -141,7 +141,7 @@ public MerchantsAsyncClient merchants() {
   }
 
   /**
-   * Returns the PayoutsAsyncClient client exposing endpoints tagged with "Payouts".
+   * Returns the PayoutsAsyncClient client for the "Payouts" API group.
    *
    * @return Client for the associated API group.
    */
@@ -150,7 +150,7 @@ public PayoutsAsyncClient payouts() {
   }
 
   /**
-   * Returns the ReadersAsyncClient client exposing endpoints tagged with "Readers".
+   * Returns the ReadersAsyncClient client for the "Readers" API group.
    *
    * @return Client for the associated API group.
    */
@@ -159,7 +159,7 @@ public ReadersAsyncClient readers() {
   }
 
   /**
-   * Returns the ReceiptsAsyncClient client exposing endpoints tagged with "Receipts".
+   * Returns the ReceiptsAsyncClient client for the "Receipts" API group.
    *
    * @return Client for the associated API group.
    */
@@ -168,7 +168,7 @@ public ReceiptsAsyncClient receipts() {
   }
 
   /**
-   * Returns the RolesAsyncClient client exposing endpoints tagged with "Roles".
+   * Returns the RolesAsyncClient client for the "Roles" API group.
    *
    * @return Client for the associated API group.
    */
@@ -177,7 +177,7 @@ public RolesAsyncClient roles() {
   }
 
   /**
-   * Returns the SubaccountsAsyncClient client exposing endpoints tagged with "Subaccounts".
+   * Returns the SubaccountsAsyncClient client for the "Subaccounts" API group.
    *
    * @return Client for the associated API group.
    */
@@ -186,7 +186,7 @@ public SubaccountsAsyncClient subaccounts() {
   }
 
   /**
-   * Returns the TransactionsAsyncClient client exposing endpoints tagged with "Transactions".
+   * Returns the TransactionsAsyncClient client for the "Transactions" API group.
    *
    * @return Client for the associated API group.
    */

diff --git a/src/main/java/com/sumup/sdk/SumUpClient.java b/src/main/java/com/sumup/sdk/SumUpClient.java
@@ -96,7 +96,7 @@ public ApiClient apiClient() {
   }
 
   /**
-   * Returns the CheckoutsClient client exposing endpoints tagged with "Checkouts".
+   * Returns the CheckoutsClient client for the "Checkouts" API group.
    *
    * @return Client for the associated API group.
    */
@@ -105,7 +105,7 @@ public CheckoutsClient checkouts() {
   }
 
   /**
-   * Returns the CustomersClient client exposing endpoints tagged with "Customers".
+   * Returns the CustomersClient client for the "Customers" API group.
    *
    * @return Client for the associated API group.
    */
@@ -114,7 +114,7 @@ public CustomersClient customers() {
   }
 
   /**
-   * Returns the MembersClient client exposing endpoints tagged with "Members".
+   * Returns the MembersClient client for the "Members" API group.
    *
    * @return Client for the associated API group.
    */
@@ -123,7 +123,7 @@ public MembersClient members() {
   }
 
   /**
-   * Returns the MembershipsClient client exposing endpoints tagged with "Memberships".
+   * Returns the MembershipsClient client for the "Memberships" API group.
    *
    * @return Client for the associated API group.
    */
@@ -132,7 +132,7 @@ public MembershipsClient memberships() {
   }
 
   /**
-   * Returns the MerchantsClient client exposing endpoints tagged with "Merchants".
+   * Returns the MerchantsClient client for the "Merchants" API group.
    *
    * @return Client for the associated API group.
    */
@@ -141,7 +141,7 @@ public MerchantsClient merchants() {
   }
 
   /**
-   * Returns the PayoutsClient client exposing endpoints tagged with "Payouts".
+   * Returns the PayoutsClient client for the "Payouts" API group.
    *
    * @return Client for the associated API group.
    */
@@ -150,7 +150,7 @@ public PayoutsClient payouts() {
   }
 
   /**
-   * Returns the ReadersClient client exposing endpoints tagged with "Readers".
+   * Returns the ReadersClient client for the "Readers" API group.
    *
    * @return Client for the associated API group.
    */
@@ -159,7 +159,7 @@ public ReadersClient readers() {
   }
 
   /**
-   * Returns the ReceiptsClient client exposing endpoints tagged with "Receipts".
+   * Returns the ReceiptsClient client for the "Receipts" API group.
    *
    * @return Client for the associated API group.
    */
@@ -168,7 +168,7 @@ public ReceiptsClient receipts() {
   }
 
   /**
-   * Returns the RolesClient client exposing endpoints tagged with "Roles".
+   * Returns the RolesClient client for the "Roles" API group.
    *
    * @return Client for the associated API group.
    */
@@ -177,7 +177,7 @@ public RolesClient roles() {
   }
 
   /**
-   * Returns the SubaccountsClient client exposing endpoints tagged with "Subaccounts".
+   * Returns the SubaccountsClient client for the "Subaccounts" API group.
    *
    * @return Client for the associated API group.
    */
@@ -186,7 +186,7 @@ public SubaccountsClient subaccounts() {
   }
 
   /**
-   * Returns the TransactionsClient client exposing endpoints tagged with "Transactions".
+   * Returns the TransactionsClient client for the "Transactions" API group.
    *
    * @return Client for the associated API group.
    */

diff --git a/src/main/java/com/sumup/sdk/clients/CheckoutsAsyncClient.java b/src/main/java/com/sumup/sdk/clients/CheckoutsAsyncClient.java
@@ -11,7 +11,14 @@
 import java.util.Objects;
 import java.util.concurrent.CompletableFuture;
 
-/** Client for the "Checkouts" API group. */
+/**
+ * Client for the "Checkouts" API group.
+ *
+ * <p>Accept payments from your end users by adding the Checkouts model to your platform. SumUp
+ * supports standard and single payment 3DS checkout flows. The Checkout model allows creating,
+ * listing, retrieving, processing and deactivating checkouts. A payment is completed by creating a
+ * checkout and then processing the checkout.
+ */
 public final class CheckoutsAsyncClient {
   private final ApiClient apiClient;
 

diff --git a/src/main/java/com/sumup/sdk/clients/CheckoutsClient.java b/src/main/java/com/sumup/sdk/clients/CheckoutsClient.java
@@ -10,7 +10,14 @@
 import java.util.Map;
 import java.util.Objects;
 
-/** Client for the "Checkouts" API group. */
+/**
+ * Client for the "Checkouts" API group.
+ *
+ * <p>Accept payments from your end users by adding the Checkouts model to your platform. SumUp
+ * supports standard and single payment 3DS checkout flows. The Checkout model allows creating,
+ * listing, retrieving, processing and deactivating checkouts. A payment is completed by creating a
+ * checkout and then processing the checkout.
+ */
 public final class CheckoutsClient {
   private final ApiClient apiClient;
 

diff --git a/src/main/java/com/sumup/sdk/clients/CustomersAsyncClient.java b/src/main/java/com/sumup/sdk/clients/CustomersAsyncClient.java
@@ -9,7 +9,14 @@
 import java.util.Objects;
 import java.util.concurrent.CompletableFuture;
 
-/** Client for the "Customers" API group. */
+/**
+ * Client for the "Customers" API group.
+ *
+ * <p>Allow your regular customers to save their information with the Customers model. This will
+ * prevent re-entering payment instrument information for recurring payments on your platform.
+ * Depending on the needs you can allow, creating, listing or deactivating payment instruments &
+ * creating, retrieving and updating customers.
+ */
 public final class CustomersAsyncClient {
   private final ApiClient apiClient;
 

diff --git a/src/main/java/com/sumup/sdk/clients/CustomersClient.java b/src/main/java/com/sumup/sdk/clients/CustomersClient.java
@@ -8,7 +8,14 @@
 import com.sumup.sdk.core.RequestOptions;
 import java.util.Objects;
 
-/** Client for the "Customers" API group. */
+/**
+ * Client for the "Customers" API group.
+ *
+ * <p>Allow your regular customers to save their information with the Customers model. This will
+ * prevent re-entering payment instrument information for recurring payments on your platform.
+ * Depending on the needs you can allow, creating, listing or deactivating payment instruments &
+ * creating, retrieving and updating customers.
+ */
 public final class CustomersClient {
   private final ApiClient apiClient;
 

diff --git a/src/main/java/com/sumup/sdk/clients/MembersAsyncClient.java b/src/main/java/com/sumup/sdk/clients/MembersAsyncClient.java
@@ -11,7 +11,12 @@
 import java.util.Objects;
 import java.util.concurrent.CompletableFuture;
 
-/** Client for the "Members" API group. */
+/**
+ * Client for the "Members" API group.
+ *
+ * <p>Endpoints to manage account members. Members are users that have membership within merchant
+ * accounts.
+ */
 public final class MembersAsyncClient {
   private final ApiClient apiClient;
 

diff --git a/src/main/java/com/sumup/sdk/clients/MembersClient.java b/src/main/java/com/sumup/sdk/clients/MembersClient.java
@@ -10,7 +10,12 @@
 import java.util.Map;
 import java.util.Objects;
 
-/** Client for the "Members" API group. */
+/**
+ * Client for the "Members" API group.
+ *
+ * <p>Endpoints to manage account members. Members are users that have membership within merchant
+ * accounts.
+ */
 public final class MembersClient {
   private final ApiClient apiClient;