Merge pull request #770 from danielgtaylor/group-convenience

feat: better group+convenience function interop

Author: danielgtaylor

group.go

@@ -127,7 +127,34 @@ func (g *Group) UseSimpleModifier(modifier func(o *Operation)) {
 // operation, in the order they were added. This is useful for modifying an
 // operation before it is registered with the router or OpenAPI document.
 func (g *Group) ModifyOperation(op *Operation, next func(*Operation)) {
-	chain := next
+	chain := func(op *Operation) {
+		// If this came from unmodified convenience functions, we may need to
+		// regenerate the operation ID and summary as they are based on things
+		// like the path which may have changed.
+		if op.Metadata != nil {
+			// Copy so we don't modify the original map.
+			meta := make(map[string]any, len(op.Metadata))
+			for k, v := range op.Metadata {
+				meta[k] = v
+			}
+			op.Metadata = meta
+
+			// If the conveniences are set, we need to regenerate the operation ID and
+			// summary based on the new path. We also update the metadata to reflect
+			// the new generated operation ID and summary so groups of groups can
+			// continue to modify them as needed.
+			if op.Metadata["_convenience_id"] == op.OperationID {
+				op.OperationID = GenerateOperationID(op.Method, op.Path, op.Metadata["_convenience_id_out"])
+				op.Metadata["_convenience_id"] = op.OperationID
+			}
+			if op.Metadata["_convenience_summary"] == op.Summary {
+				op.Summary = GenerateSummary(op.Method, op.Path, op.Metadata["_convenience_summary_out"])
+				op.Metadata["_convenience_summary"] = op.Summary
+			}
+		}
+		// Call the final handler.
+		next(op)
+	}
 	for i := len(g.modifiers) - 1; i >= 0; i-- {
 		// Use an inline func to provide a closure around the index & chain.
 		func(i int, n func(*Operation)) {

group_test.go

@@ -51,6 +51,70 @@ func TestGroupMultiPrefix(t *testing.T) {
 	assert.Equal(t, http.StatusNoContent, resp.Result().StatusCode)
 }
 
+func TestGroupConvenienceEquivalency(t *testing.T) {
+	_, api := humatest.New(t)
+
+	// Register a normal route via convenience function.
+	huma.Get(api, "/v1/users", func(ctx context.Context, input *struct{}) (*struct{}, error) {
+		return nil, nil
+	})
+
+	// Upgrade to groups and expect the same behavior.
+	grp2 := huma.NewGroup(api, "/v2")
+
+	huma.Get(grp2, "/users", func(ctx context.Context, input *struct{}) (*struct{}, error) {
+		return nil, nil
+	})
+
+	// Ensure convenience overrides still work.
+	grp3 := huma.NewGroup(api, "/v3")
+	huma.Get(grp3, "/users", func(ctx context.Context, input *struct{}) (*struct{}, error) {
+		return nil, nil
+	}, func(o *huma.Operation) {
+		o.OperationID = "custom-id"
+		o.Summary = "Custom summary"
+	})
+
+	// Ensure group overrides still work.
+	grp4 := huma.NewGroup(api, "/v4")
+	grp4.UseModifier(func(op *huma.Operation, next func(*huma.Operation)) {
+		op.OperationID = "custom-id"
+		op.Summary = "Custom summary"
+		next(op)
+	})
+	huma.Get(grp4, "/users", func(ctx context.Context, input *struct{}) (*struct{}, error) {
+		return nil, nil
+	})
+
+	// Groups of groups should continue to work as well, including both groups in
+	// the generated ID/summary.
+	grp5 := huma.NewGroup(api, "/v5")
+	grp6 := huma.NewGroup(grp5, "/users")
+	huma.Get(grp6, "/", func(ctx context.Context, input *struct{}) (*struct{}, error) {
+		return nil, nil
+	})
+
+	oapi := api.OpenAPI()
+
+	assert.NotNil(t, oapi.Paths["/v1/users"])
+	assert.NotNil(t, oapi.Paths["/v2/users"])
+	assert.NotNil(t, oapi.Paths["/v3/users"])
+	assert.NotNil(t, oapi.Paths["/v4/users"])
+	assert.NotNil(t, oapi.Paths["/v5/users/"])
+
+	assert.Equal(t, "get-v1-users", oapi.Paths["/v1/users"].Get.OperationID)
+	assert.Equal(t, "get-v2-users", oapi.Paths["/v2/users"].Get.OperationID)
+	assert.Equal(t, "custom-id", oapi.Paths["/v3/users"].Get.OperationID)
+	assert.Equal(t, "custom-id", oapi.Paths["/v4/users"].Get.OperationID)
+	assert.Equal(t, "get-v5-users", oapi.Paths["/v5/users/"].Get.OperationID)
+
+	assert.Equal(t, "Get v1 users", oapi.Paths["/v1/users"].Get.Summary)
+	assert.Equal(t, "Get v2 users", oapi.Paths["/v2/users"].Get.Summary)
+	assert.Equal(t, "Custom summary", oapi.Paths["/v3/users"].Get.Summary)
+	assert.Equal(t, "Custom summary", oapi.Paths["/v4/users"].Get.Summary)
+	assert.Equal(t, "Get v5 users", oapi.Paths["/v5/users/"].Get.Summary)
+}
+
 func TestGroupCustomizations(t *testing.T) {
 	_, api := humatest.New(t)
 

huma.go

@@ -2025,15 +2025,27 @@ func OperationTags(tags ...string) func(o *Operation) {
 
 func convenience[I, O any](api API, method, path string, handler func(context.Context, *I) (*O, error), operationHandlers ...func(o *Operation)) {
 	var o *O
+	opID := GenerateOperationID(method, path, o)
+	opSummary := GenerateSummary(method, path, o)
 	operation := Operation{
-		OperationID: GenerateOperationID(method, path, o),
-		Summary:     GenerateSummary(method, path, o),
+		OperationID: opID,
+		Summary:     opSummary,
 		Method:      method,
 		Path:        path,
+		Metadata:    map[string]any{},
 	}
 	for _, oh := range operationHandlers {
 		oh(&operation)
 	}
+	// If not modified, hint that these were auto-generated!
+	if operation.OperationID == opID {
+		operation.Metadata["_convenience_id"] = opID
+		operation.Metadata["_convenience_id_out"] = o
+	}
+	if operation.Summary == opSummary {
+		operation.Metadata["_convenience_summary"] = opSummary
+		operation.Metadata["_convenience_summary_out"] = o
+	}
 	Register(api, operation, handler)
 }