chore: synced file(s) with sumup/apis (#237)

Author: appscisumup

DOCUMENTATION.md

@@ -45,6 +45,19 @@ func operationParamsGodoc(name string, operation *v3.Operation) string {
 	return formatGodoc(fmt.Sprintf("%s are query parameters for %s.", name, operation.OperationId))
 }
 
+// clientGodoc creates godoc for a generated client from the OpenAPI tag description.
+func clientGodoc(name string, tag *base.Tag) string {
+	out := new(strings.Builder)
+
+	fmt.Fprintf(out, "%s provides access to the %s API.", name, cmp.Or(tag.Name, "tag"))
+
+	if tag != nil && strings.TrimSpace(tag.Description) != "" {
+		fmt.Fprintf(out, "\n\n%s", strings.TrimSpace(tag.Description))
+	}
+
+	return formatGodoc(out.String())
+}
+
 // schemaGodoc creates godoc for a schema.
 func schemaGodoc(name string, schema *base.Schema) string {
 	out := new(strings.Builder)

checkouts.go

@@ -25,6 +25,7 @@ type templateData struct {
 	Aliases     []Alias
 	Types       []Writable
 	Service     string
+	ServiceDoc  string
 	Methods     []*Method
 }
 
@@ -75,6 +76,7 @@ func (b *Builder) generateResource(tagName string, paths *v3.Paths) error {
 		Types:       types,
 		Methods:     methods,
 		Service:     strcase.ToCamel(tag.Name),
+		ServiceDoc:  clientGodoc(strcase.ToCamel(tag.Name)+"Client", tag),
 	}); err != nil {
 		return err
 	}

customers.go

@@ -32,6 +32,9 @@ import (
 {{- end }}
 
 {{ if ne (len .Methods) 0 }}
+{{- with .ServiceDoc}}
+// {{.}}
+{{- end }}
 type {{.Service}}Client struct {
 	c *client.Client
 }