feat: resource docs

codegen/internal/generator/generator.go

@@ -543,9 +543,10 @@
 			ct, ok := clientMap[clientName]
 			if !ok {
 				ct = &clientTemplateData{
 					Namespace:    g.config.Namespace,
 					ClientName:   clientName,
 					PropertyName: clientName,
+					TagDescription: findTagDescription(doc, tag),
 				}
 				clientMap[clientName] = ct
 			}
@@ -1423,6 +1424,7 @@
 	Namespace          string
 	ClientName         string
 	PropertyName       string
+	TagDescription     string
 	Operations         []operationTemplateData
 	UsesCollections    bool
 	UsesJson           bool
@@ -1492,6 +1494,21 @@
 	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>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.</remarks>
     internal CheckoutsClient(ApiClient client)
     {
         _client = client;

src/SumUp/CustomersClient.g.cs

@@ -15,6 +15,10 @@
 {
     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 & 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/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>Retrieve details for a specific transaction by it’s `id` or any other required query parameter, or list all transactions related to the merchant account.</remarks>
     internal TransactionsClient(ApiClient client)
     {
         _client = client;