feat: added name mangler options to Spec analyzer and FlattenOpts (#183)

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>

Author: fredbi

analyzer.go

@@ -145,19 +145,27 @@ type Spec struct {
 	enums       enumAnalysis
 	allSchemas  map[string]SchemaRef
 	allOfs      map[string]SchemaRef
+	mangler     mangling.NameMangler
 }
 
 // New takes a swagger spec object and returns an analyzed spec document.
 // The analyzed document contains a number of indices that make it easier to
 // reason about semantics of a swagger specification for use in code generation
 // or validation etc.
-func New(doc *spec.Swagger) *Spec {
+func New(doc *spec.Swagger, opts ...Option) *Spec {
+	o := &analyzerOptions{}
+	for _, opt := range opts {
+		opt(o)
+	}
+
 	a := &Spec{
 		spec:       doc,
 		references: referenceAnalysis{},
 		patterns:   patternAnalysis{},
 		enums:      enumAnalysis{},
+		mangler:    mangling.NewNameMangler(o.manglerOpts...),
 	}
+
 	a.reset()
 	a.initialize()
 
@@ -288,20 +296,6 @@ func (s *Spec) ProducesFor(operation *spec.Operation) []string {
 	return s.structMapKeys(prod)
 }
 
-func mapKeyFromParam(param *spec.Parameter) string {
-	return fmt.Sprintf("%s#%s", param.In, fieldNameFromParam(param))
-}
-
-func fieldNameFromParam(param *spec.Parameter) string {
-	// TODO: this should be x-go-name
-	if nm, ok := param.Extensions.GetString("go-name"); ok {
-		return nm
-	}
-	mangler := mangling.NewNameMangler()
-
-	return mangler.ToGoName(param.Name)
-}
-
 // ErrorOnParamFunc is a callback function to be invoked
 // whenever an error is encountered while resolving references
 // on parameters.
@@ -651,6 +645,19 @@ func (s *Spec) AllEnums() map[string][]any {
 	return cloneEnumMap(s.enums.allEnums)
 }
 
+func (s *Spec) mapKeyFromParam(param *spec.Parameter) string {
+	return fmt.Sprintf("%s#%s", param.In, s.fieldNameFromParam(param))
+}
+
+func (s *Spec) fieldNameFromParam(param *spec.Parameter) string {
+	// TODO: this should be x-go-name
+	if nm, ok := param.Extensions.GetString("go-name"); ok {
+		return nm
+	}
+
+	return s.mangler.ToGoName(param.Name)
+}
+
 func (s *Spec) structMapKeys(mp map[string]struct{}) []string {
 	if len(mp) == 0 {
 		return nil
@@ -668,7 +675,7 @@ func (s *Spec) paramsAsMap(parameters []spec.Parameter, res map[string]spec.Para
 	for _, param := range parameters {
 		pr := param
 		if pr.Ref.String() == "" {
-			res[mapKeyFromParam(&pr)] = pr
+			res[s.mapKeyFromParam(&pr)] = pr
 
 			continue
 		}
@@ -699,7 +706,7 @@ func (s *Spec) paramsAsMap(parameters []spec.Parameter, res map[string]spec.Para
 		}
 
 		pr = objAsParam
-		res[mapKeyFromParam(&pr)] = pr
+		res[s.mapKeyFromParam(&pr)] = pr
 	}
 }
 

flatten.go

@@ -554,6 +554,7 @@ func updateRefParents(allRefs map[string]spec.Ref, r *newRef) {
 	}
 }
 
+//nolint:gocognit,gocyclo,cyclop // legacy from a lot of design choices that led to concentrate the complexity just here.
 func stripOAIGenForRef(opts *FlattenOpts, k string, r *newRef) (bool, error) {
 	replacedWithComplex := false
 

flatten_name.go

@@ -273,9 +273,9 @@ func mangler(o *FlattenOpts) func(string) string {
 	if o.KeepNames {
 		return func(in string) string { return in }
 	}
-	mangler := mangling.NewNameMangler()
+	m := mangling.NewNameMangler(o.ManglerOpts...)
 
-	return mangler.ToJSONName
+	return m.ToJSONName
 }
 
 func nameFromRef(ref spec.Ref, o *FlattenOpts) string {

flatten_options.go

@@ -7,6 +7,7 @@ import (
 	"log"
 
 	"github.com/go-openapi/spec"
+	"github.com/go-openapi/swag/mangling"
 )
 
 // FlattenOpts configuration for flattening a swagger specification.
@@ -24,12 +25,13 @@ type FlattenOpts struct {
 	BasePath string // The location of the root document for this spec to resolve relative $ref
 
 	// Flattening options
-	Expand          bool // When true, skip flattening the spec and expand it instead (if Minimal is false)
-	Minimal         bool // When true, do not decompose complex structures such as allOf
-	Verbose         bool // enable some reporting on possible name conflicts detected
-	RemoveUnused    bool // When true, remove unused parameters, responses and definitions after expansion/flattening
-	ContinueOnError bool // Continue when spec expansion issues are found
-	KeepNames       bool // Do not attempt to jsonify names from references when flattening
+	Expand          bool              // When true, skip flattening the spec and expand it instead (if Minimal is false)
+	Minimal         bool              // When true, do not decompose complex structures such as allOf
+	Verbose         bool              // enable some reporting on possible name conflicts detected
+	RemoveUnused    bool              // When true, remove unused parameters, responses and definitions after expansion/flattening
+	ContinueOnError bool              // Continue when spec expansion issues are found
+	KeepNames       bool              // Do not attempt to jsonify names from references when flattening
+	ManglerOpts     []mangling.Option // Options for the name mangler used to jsonify names
 
 	/* Extra keys */
 	_ struct{} // require keys

go.work.sum

@@ -7,7 +7,7 @@ require (
 	github.com/go-openapi/loads v0.23.2
 	github.com/go-openapi/spec v0.22.4
 	github.com/go-openapi/swag/loading v0.25.5
-	github.com/go-openapi/testify/v2 v2.4.1
+	github.com/go-openapi/testify/v2 v2.4.2
 )
 
 require (

internal/testintegration/go.mod

@@ -30,8 +30,8 @@ github.com/go-openapi/swag/yamlutils v0.25.5 h1:kASCIS+oIeoc55j28T4o8KwlV2S4ZLPT
 github.com/go-openapi/swag/yamlutils v0.25.5/go.mod h1:Gek1/SjjfbYvM+Iq4QGwa/2lEXde9n2j4a3wI3pNuOQ=
 github.com/go-openapi/testify/enable/yaml/v2 v2.4.0 h1:7SgOMTvJkM8yWrQlU8Jm18VeDPuAvB/xWrdxFJkoFag=
 github.com/go-openapi/testify/enable/yaml/v2 v2.4.0/go.mod h1:14iV8jyyQlinc9StD7w1xVPW3CO3q1Gj04Jy//Kw4VM=
-github.com/go-openapi/testify/v2 v2.4.1 h1:zB34HDKj4tHwyUQHrUkpV0Q0iXQ6dUCOQtIqn8hE6Iw=
-github.com/go-openapi/testify/v2 v2.4.1/go.mod h1:HCPmvFFnheKK2BuwSA0TbbdxJ3I16pjwMkYkP4Ywn54=
+github.com/go-openapi/testify/v2 v2.4.2 h1:tiByHpvE9uHrrKjOszax7ZvKB7QOgizBWGBLuq0ePx4=
+github.com/go-openapi/testify/v2 v2.4.2/go.mod h1:SgsVHtfooshd0tublTtJ50FPKhujf47YRqauXXOUxfw=
 github.com/go-viper/mapstructure/v2 v2.5.0 h1:vM5IJoUAy3d7zRSVtIwQgBj7BiWtMPfmPEgAXnvj1Ro=
 github.com/go-viper/mapstructure/v2 v2.5.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=

internal/testintegration/go.sum

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
+// SPDX-License-Identifier: Apache-2.0
+
+package analysis
+
+import "github.com/go-openapi/swag/mangling"
+
+// Option configures the behavior of a new [Spec] analyzer.
+type Option func(*analyzerOptions)
+
+type analyzerOptions struct {
+	manglerOpts []mangling.Option
+}
+
+// WithManglerOptions sets the name mangler options used when building
+// Go identifiers from specification names (e.g. parameter names).
+func WithManglerOptions(opts ...mangling.Option) Option {
+	return func(o *analyzerOptions) {
+		o.manglerOpts = append(o.manglerOpts, opts...)
+	}
+}