feat: resource docs

codegen/internal/generator/generator.go

@@ -543,9 +543,10 @@ func (g *Generator) buildClients(doc *v3.Document) ([]clientTemplateData, error)
 			ct, ok := clientMap[clientName]
 			if !ok {
 				ct = &clientTemplateData{
-					Namespace:    g.config.Namespace,
-					ClientName:   clientName,
-					PropertyName: clientName,
+					Namespace:      g.config.Namespace,
+					ClientName:     clientName,
+					PropertyName:   clientName,
+					TagDescription: findTagDescription(doc, tag),
 				}
 				clientMap[clientName] = ct
 			}
@@ -1338,7 +1339,11 @@ func sanitizeText(value string) string {
 	value = strings.ReplaceAll(value, "\r\n", " ")
 	value = strings.ReplaceAll(value, "\n", " ")
 	value = strings.Join(strings.Fields(value), " ")
-	return value
+	return strings.NewReplacer(
+		"&", "&",
+		"<", "&lt;",
+		">", "&gt;",
+	).Replace(value)
 }
 
 func yamlNodeToString(node *yaml.Node) string {
@@ -1423,6 +1428,7 @@ type clientTemplateData struct {
 	Namespace          string
 	ClientName         string
 	PropertyName       string
+	TagDescription     string
 	Operations         []operationTemplateData
 	UsesCollections    bool
 	UsesJson           bool
@@ -1492,6 +1498,21 @@ type rootTemplateData struct {
 	Clients   []clientTemplateData
 }
 
+func findTagDescription(doc *v3.Document, tagName string) string {
+	if doc == nil || doc.Tags == nil {
+		return ""
+	}
+	for _, tag := range doc.Tags {
+		if tag == nil {
+			continue
+		}
+		if strings.EqualFold(strings.TrimSpace(tag.Name), strings.TrimSpace(tagName)) {
+			return sanitizeText(tag.Description)
+		}
+	}
+	return ""
+}
+
 type apiVersionTemplateData struct {
 	Namespace  string
 	ApiVersion string

codegen/internal/generator/templates/client.tmpl

@@ -18,6 +18,12 @@ public sealed partial class {{ .ClientName }}Client
 {
     private readonly ApiClient _client;
 
+    /// <summary>
+    /// Client for the {{ .ClientName }} API endpoints.
+    /// </summary>
+    {{- if .TagDescription }}
+    /// <remarks>{{ .TagDescription }}</remarks>
+    {{- end }}
     internal {{ .ClientName }}Client(ApiClient client)
     {
         _client = client;

codegen/internal/generator/templates/root_client.tmpl

@@ -16,6 +16,9 @@ public partial class SumUpClient
     }
 {{- range .Clients }}
 
+    /// <summary>
+    /// Access the {{ .ClientName }} API endpoints.
+    /// </summary>
     public {{ .ClientName }}Client {{ .PropertyName }} { get; private set; } = default!;
 {{- end }}
 }

src/SumUp/CheckoutsClient.g.cs

@@ -15,6 +15,10 @@ public sealed partial class CheckoutsClient
 {
     private readonly ApiClient _client;
 
+    /// <summary>
+    /// Client for the Checkouts API endpoints.
+    /// </summary>
+    /// <remarks>Checkouts represent online payment sessions that you create before attempting to charge a payer. A checkout captures the payment intent, such as the amount, currency, merchant, and optional customer or redirect settings, and then moves through its lifecycle as you process it. Use this tag to: - create a checkout before collecting or confirming payment details - process the checkout with a card, saved card, wallet, or supported alternative payment method - retrieve or list checkouts to inspect their current state and associated payment attempts - deactivate a checkout that should no longer be used Typical workflow: - create a checkout with the order amount, currency, and merchant information - process the checkout through SumUp client tools such as the [Payment Widget and Swift Checkout SDK](https://developer.sumup.com/online-payments/checkouts) - retrieve the checkout or use the Transactions endpoints to inspect the resulting payment record Checkouts are used to initiate and orchestrate online payments. Transactions remain the authoritative record of the resulting payment outcome.</remarks>
     internal CheckoutsClient(ApiClient client)
     {
         _client = client;

src/SumUp/CustomersClient.g.cs

@@ -15,6 +15,10 @@ public sealed partial class CustomersClient
 {
     private readonly ApiClient _client;
 
+    /// <summary>
+    /// Client for the Customers API endpoints.
+    /// </summary>
+    /// <remarks>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 &amp; creating, retrieving and updating customers.</remarks>
     internal CustomersClient(ApiClient client)
     {
         _client = client;

src/SumUp/MembersClient.g.cs

@@ -15,6 +15,10 @@ public sealed partial class MembersClient
 {
     private readonly ApiClient _client;
 
+    /// <summary>
+    /// Client for the Members API endpoints.
+    /// </summary>
+    /// <remarks>Endpoints to manage account members. Members are users that have membership within merchant accounts.</remarks>
     internal MembersClient(ApiClient client)
     {
         _client = client;

src/SumUp/MembershipsClient.g.cs

@@ -15,6 +15,10 @@ public sealed partial class MembershipsClient
 {
     private readonly ApiClient _client;
 
+    /// <summary>
+    /// Client for the Memberships API endpoints.
+    /// </summary>
+    /// <remarks>Endpoints to manage user's memberships. Memberships are used to connect the user to merchant accounts and to grant them access to the merchant's resources via roles.</remarks>
     internal MembershipsClient(ApiClient client)
     {
         _client = client;

src/SumUp/MerchantsClient.g.cs

@@ -14,6 +14,10 @@ public sealed partial class MerchantsClient
 {
     private readonly ApiClient _client;
 
+    /// <summary>
+    /// Client for the Merchants API endpoints.
+    /// </summary>
+    /// <remarks>Merchant account represents a single business entity at SumUp.</remarks>
     internal MerchantsClient(ApiClient client)
     {
         _client = client;

src/SumUp/Models/PersonalProfilePayloadLegacy.g.cs

@@ -22,7 +22,7 @@ public sealed partial class PersonalProfilePayloadLegacy
     /// <summary>Mobile phone number</summary>
     [JsonPropertyName("mobile_phone")]
     public string? MobilePhone { get; set; }
-    /// <summary>National identification id. Country specific. Ex CPF &#40;Brazil&#41;, DNI (Spain), PESEL (Poland)</summary>
+    /// <summary>National identification id. Country specific. Ex CPF &amp;#40;Brazil&amp;#41;, DNI (Spain), PESEL (Poland)</summary>
     [JsonPropertyName("national_id")]
     public string? NationalId { get; set; }
 }

src/SumUp/PayoutsClient.g.cs

@@ -15,6 +15,10 @@ public sealed partial class PayoutsClient
 {
     private readonly ApiClient _client;
 
+    /// <summary>
+    /// Client for the Payouts API endpoints.
+    /// </summary>
+    /// <remarks>The Payouts model will allow you to track funds you’ve received from SumUp. You can receive a detailed payouts list with information like dates, fees, references and statuses, using the `List payouts` endpoint.</remarks>
     internal PayoutsClient(ApiClient client)
     {
         _client = client;

src/SumUp/ReadersClient.g.cs

@@ -14,6 +14,10 @@ public sealed partial class ReadersClient
 {
     private readonly ApiClient _client;
 
+    /// <summary>
+    /// Client for the Readers API endpoints.
+    /// </summary>
+    /// <remarks>A reader represents a device that accepts payments. You can use the SumUp Solo to accept in-person payments.</remarks>
     internal ReadersClient(ApiClient client)
     {
         _client = client;

src/SumUp/ReceiptsClient.g.cs

@@ -14,6 +14,10 @@ public sealed partial class ReceiptsClient
 {
     private readonly ApiClient _client;
 
+    /// <summary>
+    /// Client for the Receipts API endpoints.
+    /// </summary>
+    /// <remarks>The Receipts model obtains receipt-like details for specific transactions.</remarks>
     internal ReceiptsClient(ApiClient client)
     {
         _client = client;

src/SumUp/RolesClient.g.cs

@@ -14,6 +14,10 @@ public sealed partial class RolesClient
 {
     private readonly ApiClient _client;
 
+    /// <summary>
+    /// Client for the Roles API endpoints.
+    /// </summary>
+    /// <remarks>Endpoints to manage custom roles. Custom roles allow you to tailor roles from individual permissions to match your needs. Once created, you can assign your custom roles to your merchant account members using the memberships.</remarks>
     internal RolesClient(ApiClient client)
     {
         _client = client;

src/SumUp/SubaccountsClient.g.cs

@@ -15,6 +15,10 @@ public sealed partial class SubaccountsClient
 {
     private readonly ApiClient _client;
 
+    /// <summary>
+    /// Client for the Subaccounts API endpoints.
+    /// </summary>
+    /// <remarks>Endpoints for managing merchant sub-accounts (operators).</remarks>
     internal SubaccountsClient(ApiClient client)
     {
         _client = client;

src/SumUp/SumUpClient.g.cs

@@ -22,25 +22,58 @@ partial void InitializeGeneratedClients(ApiClient apiClient)
         Transactions = new TransactionsClient(apiClient);
     }
 
+    /// <summary>
+    /// Access the Checkouts API endpoints.
+    /// </summary>
     public CheckoutsClient Checkouts { get; private set; } = default!;
 
+    /// <summary>
+    /// Access the Customers API endpoints.
+    /// </summary>
     public CustomersClient Customers { get; private set; } = default!;
 
+    /// <summary>
+    /// Access the Members API endpoints.
+    /// </summary>
     public MembersClient Members { get; private set; } = default!;
 
+    /// <summary>
+    /// Access the Memberships API endpoints.
+    /// </summary>
     public MembershipsClient Memberships { get; private set; } = default!;
 
+    /// <summary>
+    /// Access the Merchants API endpoints.
+    /// </summary>
     public MerchantsClient Merchants { get; private set; } = default!;
 
+    /// <summary>
+    /// Access the Payouts API endpoints.
+    /// </summary>
     public PayoutsClient Payouts { get; private set; } = default!;
 
+    /// <summary>
+    /// Access the Readers API endpoints.
+    /// </summary>
     public ReadersClient Readers { get; private set; } = default!;
 
+    /// <summary>
+    /// Access the Receipts API endpoints.
+    /// </summary>
     public ReceiptsClient Receipts { get; private set; } = default!;
 
+    /// <summary>
+    /// Access the Roles API endpoints.
+    /// </summary>
     public RolesClient Roles { get; private set; } = default!;
 
+    /// <summary>
+    /// Access the Subaccounts API endpoints.
+    /// </summary>
     public SubaccountsClient Subaccounts { get; private set; } = default!;
 
+    /// <summary>
+    /// Access the Transactions API endpoints.
+    /// </summary>
     public TransactionsClient Transactions { get; private set; } = default!;
 }

src/SumUp/TransactionsClient.g.cs

@@ -15,6 +15,10 @@ public sealed partial class TransactionsClient
 {
     private readonly ApiClient _client;
 
+    /// <summary>
+    /// Client for the Transactions API endpoints.
+    /// </summary>
+    /// <remarks>Transactions represent completed or attempted payment operations processed for a merchant account. A transaction contains the core payment result, such as the amount, currency, payment method, creation time, and current high-level status. In addition to the main payment outcome, a transaction can contain related events that describe what happened after the original payment attempt. These events provide visibility into the financial lifecycle of the transaction, for example: - `PAYOUT`: the payment being prepared for payout or included in a payout to the merchant - `REFUND`: money returned to the payer - `CHARGE_BACK`: money reversed after the original payment - `PAYOUT_DEDUCTION`: an amount deducted from a payout to cover a refund or chargeback From an integrator's perspective, transactions are the authoritative record of payment outcomes. Use this tag to: - list transactions for reporting, reconciliation, and customer support workflows - retrieve a single transaction when you need the latest payment details - inspect `simple_status` for the current merchant-facing outcome of the payment - inspect `events` or `transaction_events` when you need refund, payout, or chargeback history Typical workflow: - create and process payments through the Checkouts endpoints - use the Transactions endpoints to read the resulting payment records - use the returned statuses and events to update your own order, accounting, or support systems</remarks>
     internal TransactionsClient(ApiClient client)
     {
         _client = client;