From 8f3592f30ae9fef15121359bf44400aea2030b73 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matou=C5=A1=20Dzivjak?= Date: Fri, 20 Nov 2026 13:56:35 +0100 Subject: [PATCH 1/2] feat(codegen): support nested SDK resources --- codegen/internal/generator/model.go | 40 +++++++++++- codegen/internal/generator/render.go | 26 +++++--- codegen/internal/generator/samples.go | 5 +- codegen/internal/generator/tag_hierarchy.go | 60 ++++++++++++++++++ .../internal/generator/tag_hierarchy_test.go | 62 +++++++++++++++++++ .../internal/generator/templates/client.tmpl | 13 ++++ .../generator/templates/client_async.tmpl | 13 ++++ 7 files changed, 208 insertions(+), 11 deletions(-) create mode 100644 codegen/internal/generator/tag_hierarchy.go create mode 100644 codegen/internal/generator/tag_hierarchy_test.go diff --git a/codegen/internal/generator/model.go b/codegen/internal/generator/model.go index 2f5d192c..840ad7cd 100644 --- a/codegen/internal/generator/model.go +++ b/codegen/internal/generator/model.go @@ -28,10 +28,14 @@ type clientModel struct { FieldName string Package string Methods []operationModel + Nested bool + Children []clientModel + AccessPath string } // operationModel stores the derived metadata for one OpenAPI operation. type operationModel struct { + Alias bool OperationID string MethodName string SummaryLines []string @@ -147,6 +151,10 @@ func buildModel(doc *v3.Document, params Params) (sdkModel, error) { } } groups := map[string][]operationModel{} + parents, err := readResourceParents(doc) + if err != nil { + return sdkModel{}, err + } if doc.Paths != nil && doc.Paths.PathItems != nil && doc.Paths.PathItems.Len() > 0 { for path, item := range doc.Paths.PathItems.FromOldest() { if item == nil { @@ -162,7 +170,10 @@ func buildModel(doc *v3.Document, params Params) (sdkModel, error) { } opModel := convertOperation(method, path, item, operation, resolver) tag := opModel.TagName - groups[tag] = append(groups[tag], opModel) + for owner := tag; owner != ""; owner = parents[owner].tag { + opModel.Alias = owner != tag + groups[owner] = append(groups[owner], opModel) + } } } } @@ -198,7 +209,7 @@ func buildModel(doc *v3.Document, params Params) (sdkModel, error) { className += suffix } - clients = append(clients, clientModel{ + client := clientModel{ TagName: tag, TagDescriptionLines: tagDescriptions[tag], ClassName: className, @@ -206,7 +217,30 @@ func buildModel(doc *v3.Document, params Params) (sdkModel, error) { FieldName: fieldName, Package: params.clientPackage(), Methods: ops, - }) + } + if parent := parents[tag]; parent.tag != "" { + client.Nested = true + client.AccessorName = camelCase(parent.label, "client") + client.FieldName = client.AccessorName + } + clients = append(clients, client) + } + byTag := make(map[string]*clientModel, len(clients)) + for i := range clients { + byTag[clients[i].TagName] = &clients[i] + } + for i := range clients { + client := &clients[i] + path := client.AccessorName + "()" + for ancestor := parents[client.TagName].tag; ancestor != ""; ancestor = parents[ancestor].tag { + path = byTag[ancestor].AccessorName + "()." + path + } + client.AccessPath = path + if parent := byTag[parents[client.TagName].tag]; parent != nil { + parent.Children = append(parent.Children, clientModel{ + ClassName: client.ClassName, AccessorName: client.AccessorName, FieldName: client.FieldName, + }) + } } schemas := buildSchemas(doc, params, resolver) diff --git a/codegen/internal/generator/render.go b/codegen/internal/generator/render.go index a8c5f901..6a9f9d84 100644 --- a/codegen/internal/generator/render.go +++ b/codegen/internal/generator/render.go @@ -5,6 +5,7 @@ import ( "fmt" "os" "path/filepath" + "slices" "sort" "strconv" "strings" @@ -162,19 +163,26 @@ type operationTemplateData struct { // clientTemplateData contains the data required to render a single client // class. type clientTemplateData struct { - Package string - ClassName string - TagName string + Children []clientModel + Package string + ClassName string + TagName string TagDescriptionLines []string - Imports []string - Operations []operationTemplateData - QueryStructs []*parameterGroupModel - HeaderStructs []*parameterGroupModel + Imports []string + Operations []operationTemplateData + QueryStructs []*parameterGroupModel + HeaderStructs []*parameterGroupModel } // prepareClientTemplateData converts an internal client model into a richer // structure that is easier for templates to consume. func prepareClientTemplateData(client clientModel, className string, async bool) clientTemplateData { + children := slices.Clone(client.Children) + if async { + for i := range children { + children[i].ClassName = asyncClientClassName(children[i].ClassName) + } + } importSet := map[string]struct{}{ "com.sumup.sdk.core.ApiClient": {}, "com.sumup.sdk.core.ApiException": {}, @@ -318,6 +326,7 @@ func prepareClientTemplateData(client clientModel, className string, async bool) sort.Strings(imports) return clientTemplateData{ + Children: children, Package: client.Package, ClassName: className, TagName: client.TagName, @@ -339,6 +348,9 @@ func prepareSumUpClientData(model sdkModel, className string, async bool) map[st } clientInfos := make([]map[string]string, 0, len(model.Clients)) for _, client := range model.Clients { + if client.Nested { + continue + } clientClass := client.ClassName if async { clientClass = asyncClientClassName(clientClass) diff --git a/codegen/internal/generator/samples.go b/codegen/internal/generator/samples.go index fb356982..8030401b 100644 --- a/codegen/internal/generator/samples.go +++ b/codegen/internal/generator/samples.go @@ -75,6 +75,9 @@ func BuildSamples(params Params, sdkVersion string) (*SampleCatalog, error) { samples := make([]Sample, 0) for _, client := range model.Clients { for _, operation := range client.Methods { + if operation.Alias { + continue + } for _, example := range operationRequestExamples(operation.Operation) { renderer := javaSampleRenderer{registry: registry} source, err := renderer.render(client, operation, example) @@ -143,7 +146,7 @@ func (r javaSampleRenderer) render(client clientModel, operation operationModel, } className := pascalCase(operation.OperationID+" "+example.name, "Sample") - call := "client." + client.AccessorName + "()." + operation.MethodName + "(" + call := "client." + client.AccessPath + "." + operation.MethodName + "(" if len(args) > 0 { call += "\n" for i, arg := range args { diff --git a/codegen/internal/generator/tag_hierarchy.go b/codegen/internal/generator/tag_hierarchy.go new file mode 100644 index 00000000..bcc3751d --- /dev/null +++ b/codegen/internal/generator/tag_hierarchy.go @@ -0,0 +1,60 @@ +package generator + +import ( + "cmp" + "fmt" + + v3 "github.com/pb33f/libopenapi/datamodel/high/v3" +) + +type resourceParent struct { + tag string + label string +} + +func readResourceParents(doc *v3.Document) (map[string]resourceParent, error) { + if doc.Extensions == nil { + return nil, nil + } + node, ok := doc.Extensions.Get("x-tagGroups") + if !ok { + return nil, nil + } + var groups []struct { + Name string `yaml:"name"` + Tags []string `yaml:"tags"` + } + if err := node.Decode(&groups); err != nil { + return nil, fmt.Errorf("decode x-tagGroups: %w", err) + } + labels := make(map[string]string, len(doc.Tags)) + for _, tag := range doc.Tags { + var displayName string + if tag.Extensions != nil { + if label, ok := tag.Extensions.Get("x-displayName"); ok { + if err := label.Decode(&displayName); err != nil { + return nil, fmt.Errorf("decode x-displayName for %s: %w", tag.Name, err) + } + } + } + labels[tag.Name] = cmp.Or(displayName, tag.Name) + } + parents := map[string]resourceParent{} + for _, group := range groups { + if labels[group.Name] == "" { + continue + } + for _, child := range group.Tags { + if child == group.Name || labels[child] == "" || parents[child].tag != "" { + continue + } + for ancestor := group.Name; ancestor != ""; ancestor = parents[ancestor].tag { + if ancestor == child { + return nil, fmt.Errorf("tag hierarchy contains a cycle at %s", child) + } + } + parents[child] = resourceParent{tag: group.Name, label: labels[child]} + } + } + return parents, nil +} diff --git a/codegen/internal/generator/tag_hierarchy_test.go b/codegen/internal/generator/tag_hierarchy_test.go new file mode 100644 index 00000000..df0baefd --- /dev/null +++ b/codegen/internal/generator/tag_hierarchy_test.go @@ -0,0 +1,62 @@ +package generator + +import ( + "github.com/pb33f/libopenapi" + "testing" +) + +func TestNestedReaderResources(t *testing.T) { + t.Parallel() + + doc, err := libopenapi.NewDocument([]byte(` +openapi: 3.1.0 +info: {title: Readers, version: 1.0.0} +tags: + - name: Readers + - name: ReaderCheckouts + x-displayName: Checkouts +x-tagGroups: + - name: Readers + tags: [ReaderCheckouts] +paths: + /readers/checkouts: + get: + operationId: ListReaders + tags: [Readers] + responses: + '204': {description: OK} + post: + operationId: CreateReaderCheckout + tags: [ReaderCheckouts] + responses: + '204': {description: OK} +components: {schemas: {}} +`)) + if err != nil { + t.Fatal(err) + } + model, err := doc.BuildV3Model() + if err != nil { + t.Fatal(err) + } + + sdk, err := buildModel(&model.Model, Params{BasePackage: "com.sumup.sdk"}) + if err != nil { + t.Fatal(err) + } + for _, client := range sdk.Clients { + switch client.TagName { + case "Readers": + if len(client.Children) != 1 || client.Children[0].AccessorName != "checkouts" || len(client.Methods) != 2 { + t.Fatalf("expected Checkouts and both legacy operations: %+v", client) + } + case "ReaderCheckouts": + if client.AccessPath != "readers().checkouts()" || len(client.Methods) != 1 { + t.Fatalf("expected only the checkout operation on the nested client: %+v", client) + } + } + } + if len(sdk.Clients) != 2 { + t.Fatalf("expected two clients, got %d", len(sdk.Clients)) + } +} diff --git a/codegen/internal/generator/templates/client.tmpl b/codegen/internal/generator/templates/client.tmpl index bfbe438b..7e83e0d3 100644 --- a/codegen/internal/generator/templates/client.tmpl +++ b/codegen/internal/generator/templates/client.tmpl @@ -15,6 +15,9 @@ import {{ . }}; */ public final class {{ .ClassName }} { private final ApiClient apiClient; +{{- range .Children }} + private final {{ .ClassName }} {{ .FieldName }}; +{{- end }} /** * Creates a new {{ .ClassName }} instance backed by the provided ApiClient. @@ -23,7 +26,17 @@ public final class {{ .ClassName }} { */ public {{ .ClassName }}(ApiClient apiClient) { this.apiClient = Objects.requireNonNull(apiClient, "apiClient"); +{{- range .Children }} + this.{{ .FieldName }} = new {{ .ClassName }}(apiClient); +{{- end }} } +{{- range .Children }} + + /** @return the {{ .AccessorName }} client. */ + public {{ .ClassName }} {{ .AccessorName }}() { + return {{ .FieldName }}; + } +{{- end }} {{- range .Operations }} {{- $reqDecl := join .RequiredParamDecls ", " -}} diff --git a/codegen/internal/generator/templates/client_async.tmpl b/codegen/internal/generator/templates/client_async.tmpl index 335d1b83..b1c15c56 100644 --- a/codegen/internal/generator/templates/client_async.tmpl +++ b/codegen/internal/generator/templates/client_async.tmpl @@ -15,6 +15,9 @@ import {{ . }}; */ public final class {{ .ClassName }} { private final ApiClient apiClient; +{{- range .Children }} + private final {{ .ClassName }} {{ .FieldName }}; +{{- end }} /** * Creates a new {{ .ClassName }} instance backed by the provided ApiClient. @@ -23,7 +26,17 @@ public final class {{ .ClassName }} { */ public {{ .ClassName }}(ApiClient apiClient) { this.apiClient = Objects.requireNonNull(apiClient, "apiClient"); +{{- range .Children }} + this.{{ .FieldName }} = new {{ .ClassName }}(apiClient); +{{- end }} } +{{- range .Children }} + + /** @return the {{ .AccessorName }} client. */ + public {{ .ClassName }} {{ .AccessorName }}() { + return {{ .FieldName }}; + } +{{- end }} {{- range .Operations }} {{- $reqDecl := join .RequiredParamDecls ", " -}} From d2c508ac7410f28dc8ee83d5bc7918609226ecf8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matou=C5=A1=20Dzivjak?= Date: Fri, 20 Nov 2026 14:23:56 +0100 Subject: [PATCH 2/2] fix(codegen): use spec method names for nested resources --- codegen/internal/generator/model.go | 22 ++++++++++++------- codegen/internal/generator/render.go | 2 +- codegen/internal/generator/samples.go | 3 --- .../internal/generator/tag_hierarchy_test.go | 10 +++++---- .../internal/generator/templates/client.tmpl | 6 ++--- .../generator/templates/client_async.tmpl | 6 ++--- 6 files changed, 27 insertions(+), 22 deletions(-) diff --git a/codegen/internal/generator/model.go b/codegen/internal/generator/model.go index 840ad7cd..759a9f0b 100644 --- a/codegen/internal/generator/model.go +++ b/codegen/internal/generator/model.go @@ -29,13 +29,17 @@ type clientModel struct { Package string Methods []operationModel Nested bool - Children []clientModel + Children []childClient AccessPath string } +type childClient struct { + ClassName string + AccessorName string +} + // operationModel stores the derived metadata for one OpenAPI operation. type operationModel struct { - Alias bool OperationID string MethodName string SummaryLines []string @@ -170,9 +174,12 @@ func buildModel(doc *v3.Document, params Params) (sdkModel, error) { } opModel := convertOperation(method, path, item, operation, resolver) tag := opModel.TagName - for owner := tag; owner != ""; owner = parents[owner].tag { - opModel.Alias = owner != tag - groups[owner] = append(groups[owner], opModel) + groups[tag] = append(groups[tag], opModel) + for parent := parents[tag].tag; parent != ""; parent = parents[parent].tag { + if _, exists := groups[parent]; exists { + break + } + groups[parent] = nil } } } @@ -221,7 +228,6 @@ func buildModel(doc *v3.Document, params Params) (sdkModel, error) { if parent := parents[tag]; parent.tag != "" { client.Nested = true client.AccessorName = camelCase(parent.label, "client") - client.FieldName = client.AccessorName } clients = append(clients, client) } @@ -237,8 +243,8 @@ func buildModel(doc *v3.Document, params Params) (sdkModel, error) { } client.AccessPath = path if parent := byTag[parents[client.TagName].tag]; parent != nil { - parent.Children = append(parent.Children, clientModel{ - ClassName: client.ClassName, AccessorName: client.AccessorName, FieldName: client.FieldName, + parent.Children = append(parent.Children, childClient{ + ClassName: client.ClassName, AccessorName: client.AccessorName, }) } } diff --git a/codegen/internal/generator/render.go b/codegen/internal/generator/render.go index 6a9f9d84..5fa3e86c 100644 --- a/codegen/internal/generator/render.go +++ b/codegen/internal/generator/render.go @@ -163,7 +163,7 @@ type operationTemplateData struct { // clientTemplateData contains the data required to render a single client // class. type clientTemplateData struct { - Children []clientModel + Children []childClient Package string ClassName string TagName string diff --git a/codegen/internal/generator/samples.go b/codegen/internal/generator/samples.go index 8030401b..004768a9 100644 --- a/codegen/internal/generator/samples.go +++ b/codegen/internal/generator/samples.go @@ -75,9 +75,6 @@ func BuildSamples(params Params, sdkVersion string) (*SampleCatalog, error) { samples := make([]Sample, 0) for _, client := range model.Clients { for _, operation := range client.Methods { - if operation.Alias { - continue - } for _, example := range operationRequestExamples(operation.Operation) { renderer := javaSampleRenderer{registry: registry} source, err := renderer.render(client, operation, example) diff --git a/codegen/internal/generator/tag_hierarchy_test.go b/codegen/internal/generator/tag_hierarchy_test.go index df0baefd..318c3384 100644 --- a/codegen/internal/generator/tag_hierarchy_test.go +++ b/codegen/internal/generator/tag_hierarchy_test.go @@ -1,8 +1,9 @@ package generator import ( - "github.com/pb33f/libopenapi" "testing" + + "github.com/pb33f/libopenapi" ) func TestNestedReaderResources(t *testing.T) { @@ -28,6 +29,7 @@ paths: post: operationId: CreateReaderCheckout tags: [ReaderCheckouts] + x-codegen: {method_name: create} responses: '204': {description: OK} components: {schemas: {}} @@ -47,11 +49,11 @@ components: {schemas: {}} for _, client := range sdk.Clients { switch client.TagName { case "Readers": - if len(client.Children) != 1 || client.Children[0].AccessorName != "checkouts" || len(client.Methods) != 2 { - t.Fatalf("expected Checkouts and both legacy operations: %+v", client) + if len(client.Children) != 1 || client.Children[0].AccessorName != "checkouts" || len(client.Methods) != 1 || client.Methods[0].MethodName != "listReaders" { + t.Fatalf("expected Checkouts and the parent operation: %+v", client) } case "ReaderCheckouts": - if client.AccessPath != "readers().checkouts()" || len(client.Methods) != 1 { + if client.AccessPath != "readers().checkouts()" || len(client.Methods) != 1 || client.Methods[0].MethodName != "create" { t.Fatalf("expected only the checkout operation on the nested client: %+v", client) } } diff --git a/codegen/internal/generator/templates/client.tmpl b/codegen/internal/generator/templates/client.tmpl index 7e83e0d3..d699c0b3 100644 --- a/codegen/internal/generator/templates/client.tmpl +++ b/codegen/internal/generator/templates/client.tmpl @@ -16,7 +16,7 @@ import {{ . }}; public final class {{ .ClassName }} { private final ApiClient apiClient; {{- range .Children }} - private final {{ .ClassName }} {{ .FieldName }}; + private final {{ .ClassName }} {{ .AccessorName }}; {{- end }} /** @@ -27,14 +27,14 @@ public final class {{ .ClassName }} { public {{ .ClassName }}(ApiClient apiClient) { this.apiClient = Objects.requireNonNull(apiClient, "apiClient"); {{- range .Children }} - this.{{ .FieldName }} = new {{ .ClassName }}(apiClient); + this.{{ .AccessorName }} = new {{ .ClassName }}(apiClient); {{- end }} } {{- range .Children }} /** @return the {{ .AccessorName }} client. */ public {{ .ClassName }} {{ .AccessorName }}() { - return {{ .FieldName }}; + return {{ .AccessorName }}; } {{- end }} diff --git a/codegen/internal/generator/templates/client_async.tmpl b/codegen/internal/generator/templates/client_async.tmpl index b1c15c56..04610361 100644 --- a/codegen/internal/generator/templates/client_async.tmpl +++ b/codegen/internal/generator/templates/client_async.tmpl @@ -16,7 +16,7 @@ import {{ . }}; public final class {{ .ClassName }} { private final ApiClient apiClient; {{- range .Children }} - private final {{ .ClassName }} {{ .FieldName }}; + private final {{ .ClassName }} {{ .AccessorName }}; {{- end }} /** @@ -27,14 +27,14 @@ public final class {{ .ClassName }} { public {{ .ClassName }}(ApiClient apiClient) { this.apiClient = Objects.requireNonNull(apiClient, "apiClient"); {{- range .Children }} - this.{{ .FieldName }} = new {{ .ClassName }}(apiClient); + this.{{ .AccessorName }} = new {{ .ClassName }}(apiClient); {{- end }} } {{- range .Children }} /** @return the {{ .AccessorName }} client. */ public {{ .ClassName }} {{ .AccessorName }}() { - return {{ .FieldName }}; + return {{ .AccessorName }}; } {{- end }}