fix: handle duplicate path parameters in OpenAPI specs (oapi-codegen#2220)

Some real-world OpenAPI specs (e.g. Keycloak) reuse the same path
parameter more than once in a single URI, such as:
/clients/{client-uuid}/roles/{role-name}/composites/clients/{client-uuid}

Previously this caused a "has 4 positional parameters, but spec has 3
declared" error because SortParamsByPath compared raw URI placeholder
count against unique declared parameters.

Fix this by deduplicating the path parameters extracted from the URI
(preserving first-occurrence order) before matching them against the
spec declared parameters. This is the right level to fix the issue
rather than scattering dedup logic across template helpers.

Fixes oapi-codegen#1574
Supersedes oapi-codegen#2175

Co-authored-by: Junior Rantila <junior.rantila@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

pkg/codegen/codegen_test.go

@@ -227,5 +227,65 @@ func (t *ExampleSchema_Item) FromExternalRef0NewPet(v externalRef0.NewPet) error
 `)
 }
 
+func TestDuplicatePathParameter(t *testing.T) {
+	// Regression test for https://github.com/oapi-codegen/oapi-codegen/issues/1574
+	// Some real-world specs (e.g. Keycloak) have paths where the same parameter
+	// appears more than once: /clients/{client-uuid}/.../clients/{client-uuid}
+	spec := `
+openapi: "3.0.0"
+info:
+  version: 1.0.0
+  title: Duplicate path param test
+paths:
+  /admin/realms/{realm}/clients/{client-uuid}/roles/{role-name}/composites/clients/{client-uuid}:
+    get:
+      operationId: getCompositeRoles
+      parameters:
+        - name: realm
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: client-uuid
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: role-name
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Success
+`
+	loader := openapi3.NewLoader()
+	swagger, err := loader.LoadFromData([]byte(spec))
+	require.NoError(t, err)
+
+	opts := Configuration{
+		PackageName: "api",
+		Generate: GenerateOptions{
+			EchoServer: true,
+			Client:     true,
+			Models:     true,
+		},
+	}
+
+	code, err := Generate(swagger, opts)
+	require.NoError(t, err)
+	assert.NotEmpty(t, code)
+
+	// Verify the generated code is valid Go.
+	_, err = format.Source([]byte(code))
+	require.NoError(t, err)
+
+	// The path params should appear exactly once in the function signature.
+	assert.Contains(t, code, "realm string")
+	assert.Contains(t, code, "clientUuid string")
+	assert.Contains(t, code, "roleName string")
+}
+
 //go:embed test_spec.yaml
 var testOpenAPIDefinition string

pkg/codegen/utils.go

@@ -654,15 +654,29 @@ func ReplacePathParamsWithStr(uri string) string {
 }
 
 // SortParamsByPath reorders the given parameter definitions to match those in the path URI.
+// If a parameter appears more than once in the path (e.g. Keycloak's
+// /clients/{client-uuid}/roles/{role-name}/composites/clients/{client-uuid}),
+// duplicates are removed and only the first occurrence determines the order.
 func SortParamsByPath(path string, in []ParameterDefinition) ([]ParameterDefinition, error) {
 	pathParams := OrderedParamsFromUri(path)
+
+	// Deduplicate, preserving first-occurrence order.
+	seen := make(map[string]struct{}, len(pathParams))
+	uniqueParams := make([]string, 0, len(pathParams))
+	for _, name := range pathParams {
+		if _, exists := seen[name]; !exists {
+			seen[name] = struct{}{}
+			uniqueParams = append(uniqueParams, name)
+		}
+	}
+
 	n := len(in)
-	if len(pathParams) != n {
+	if len(uniqueParams) != n {
 		return nil, fmt.Errorf("path '%s' has %d positional parameters, but spec has %d declared",
-			path, len(pathParams), n)
+			path, len(uniqueParams), n)
 	}
-	out := make([]ParameterDefinition, len(in))
-	for i, name := range pathParams {
+	out := make([]ParameterDefinition, n)
+	for i, name := range uniqueParams {
 		p := ParameterDefinitions(in).FindByName(name)
 		if p == nil {
 			return nil, fmt.Errorf("path '%s' refers to parameter '%s', which doesn't exist in specification",

pkg/codegen/utils_test.go

@@ -462,6 +462,53 @@ func TestOrderedParamsFromUri(t *testing.T) {
 
 	result = OrderedParamsFromUri("/path/foo")
 	assert.EqualValues(t, []string{}, result)
+
+	// A parameter can appear more than once in the URI (e.g. Keycloak API).
+	// OrderedParamsFromUri faithfully returns all occurrences.
+	result = OrderedParamsFromUri("/admin/realms/{realm}/clients/{client-uuid}/roles/{role-name}/composites/clients/{client-uuid}")
+	assert.EqualValues(t, []string{"realm", "client-uuid", "role-name", "client-uuid"}, result)
+}
+
+func TestSortParamsByPath(t *testing.T) {
+	strSchema := &openapi3.Schema{Type: &openapi3.Types{"string"}}
+
+	t.Run("reorders params to match path order", func(t *testing.T) {
+		params := []ParameterDefinition{
+			{ParamName: "b", In: "path", Spec: &openapi3.Parameter{Name: "b", Schema: &openapi3.SchemaRef{Value: strSchema}}},
+			{ParamName: "a", In: "path", Spec: &openapi3.Parameter{Name: "a", Schema: &openapi3.SchemaRef{Value: strSchema}}},
+		}
+		sorted, err := SortParamsByPath("/foo/{a}/bar/{b}", params)
+		require.NoError(t, err)
+		require.Len(t, sorted, 2)
+		assert.Equal(t, "a", sorted[0].ParamName)
+		assert.Equal(t, "b", sorted[1].ParamName)
+	})
+
+	t.Run("errors on missing parameter", func(t *testing.T) {
+		params := []ParameterDefinition{
+			{ParamName: "a", In: "path", Spec: &openapi3.Parameter{Name: "a", Schema: &openapi3.SchemaRef{Value: strSchema}}},
+		}
+		_, err := SortParamsByPath("/foo/{a}/bar/{b}", params)
+		assert.Error(t, err)
+	})
+
+	t.Run("handles duplicate path parameters", func(t *testing.T) {
+		// This is the Keycloak-style path where {client-uuid} appears twice.
+		// The spec only declares 3 unique parameters.
+		params := []ParameterDefinition{
+			{ParamName: "realm", In: "path", Spec: &openapi3.Parameter{Name: "realm", Schema: &openapi3.SchemaRef{Value: strSchema}}},
+			{ParamName: "client-uuid", In: "path", Spec: &openapi3.Parameter{Name: "client-uuid", Schema: &openapi3.SchemaRef{Value: strSchema}}},
+			{ParamName: "role-name", In: "path", Spec: &openapi3.Parameter{Name: "role-name", Schema: &openapi3.SchemaRef{Value: strSchema}}},
+		}
+		path := "/admin/realms/{realm}/clients/{client-uuid}/roles/{role-name}/composites/clients/{client-uuid}"
+		sorted, err := SortParamsByPath(path, params)
+		require.NoError(t, err)
+		// Should return 3 unique params in first-occurrence order
+		require.Len(t, sorted, 3)
+		assert.Equal(t, "realm", sorted[0].ParamName)
+		assert.Equal(t, "client-uuid", sorted[1].ParamName)
+		assert.Equal(t, "role-name", sorted[2].ParamName)
+	})
 }
 
 func TestReplacePathParamsWithStr(t *testing.T) {