grpc-ecosystem/grpc-gateway · error

no description nor summary property

Error message

no description nor summary property

What it means

This error ends the same comment-attachment helper in template.go: if the target object has neither a settable Summary nor a settable Description property, the helper cannot attach proto comments anywhere and returns "no description nor summary property". It occurs when the function falls through both branches — no summary was settable and no description was settable/available — during OpenAPI template rendering.

Source

Thrown at protoc-gen-openapiv2/internal/genopenapi/template.go:2980

				// keep the comment precedence when updating the package definition
				if descriptionValue.Len() == 0 || isPackageObject {
					descriptionValue.Set(reflect.ValueOf(description))
				}
			}
			return nil
		}
	}

	// There was no summary field on the swaggerObject. Try to apply the
	// whole comment into description if the OpenAPI object description is empty.
	if descriptionValue.CanSet() {
		if descriptionValue.Len() == 0 || isPackageObject {
			descriptionValue.Set(reflect.ValueOf(strings.Join(paragraphs, paragraphDeliminator)))
		}
		return nil
	}

	return errors.New("no description nor summary property")
}

func fieldProtoComments(reg *descriptor.Registry, msg *descriptor.Message, field *descriptor.Field) string {
	protoPath := protoPathIndex(reflect.TypeOf((*descriptorpb.DescriptorProto)(nil)), "Field")
	for i, f := range msg.Fields {
		if f == field {
			return protoComments(reg, msg.File, msg.Outers, "MessageType", int32(msg.Index), protoPath, int32(i))
		}
	}
	return ""
}

func enumValueProtoComments(reg *descriptor.Registry, enum *descriptor.Enum) string {
	protoPath := protoPathIndex(reflect.TypeOf((*descriptorpb.EnumDescriptorProto)(nil)), "Value")
	var comments []string
	for idx, value := range enum.GetValue() {
		if reg.GetOmitEnumDefaultValue() && value.GetNumber() == 0 {
			continue

View on GitHub (pinned to a58a4436a3)

Solutions

1. Verify you are using the standard grpc-gateway OpenAPI object types (or compatible go-openapi/spec types) that expose Summary and Description fields.
2. Remove custom schema/object overrides that omit Summary/Description from the annotated type.
3. Align vendored go-openapi/spec version with what grpc-gateway expects (go mod tidy / update vendor).
4. Upgrade protoc-gen-openapiv2 to the latest version to pick up fixes in comment attachment.

Example fix

// before
type customObj struct { Foo string }
// after
type customObj struct {
    Summary     string
    Description string
}

v := reflect.ValueOf(obj).Elem()
if !(fieldByNameSettable(v, "Summary") || fieldByNameSettable(v, "Description")) {
    return fmt.Errorf("object %T must expose Summary or Description", obj)
}

func annotatable(obj interface{}) bool {
    v := reflect.ValueOf(obj)
    if v.Kind() != reflect.Ptr || v.Elem().Kind() != reflect.Struct { return false }
    s, d := v.Elem().FieldByName("Summary"), v.Elem().FieldByName("Description")
    return (s.IsValid() && s.CanSet()) || (d.IsValid() && d.CanSet())
}

if err := applyTemplate(...); err != nil {
    if strings.Contains(err.Error(), "no description nor summary") {
        return fmt.Errorf("unexpected object type in OpenAPI tree: %w", err)
    }
    return err
}

When it happens

Trigger: During applyTemplate when fieldProtoComments/object comment attachment runs against a reflect.Value that lacks both Summary and Description settable fields — e.g. annotating a custom or unexpected object type in the OpenAPI tree.

Common situations: Custom extensions or plugin hookouts producing object types not matching the expected OpenAPI structs; mismatched vendored copies of go-openapi/spec types; generating comments for objects the generator does not know how to annotate.

Related errors

• encountered object type with a summary, but no description
• unexpected number of yaml nodes
• only primitive and enum types are allowed in repeated path p
• only primitive and well-known types are allowed in path para
• no target service defined in the file

AI-assisted analysis of grpc-ecosystem/grpc-gateway@a58a4436a3 (2026-09-02). Data as JSON: /api/errors/d4d57a55a13599f7. Report an issue: GitHub.