grpc-ecosystem/grpc-gateway · error

encountered object type with a summary, but no description

Error message

encountered object type with a summary, but no description

What it means

This error comes from the reflection-based logic in template.go that copies proto comments (summary/description) onto schema objects. When a description paragraph was found but the target struct's Description field cannot be set via reflection (CanSet() false, meaning the field is unexported or the value is not a settable addressable field), the generator returns "encountered object type with a summary, but no description". It indicates an internal mismatch while populating comments on an OpenAPI object.

Source

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

		usingTitle = true
	}

	paragraphs := strings.Split(comment, paragraphDeliminator)

	// If there is a summary (or summary-equivalent) and it's empty, use the first
	// paragraph as summary, and the rest as description.
	if summaryValue.CanSet() {
		summary := strings.TrimSpace(paragraphs[0])
		description := strings.TrimSpace(strings.Join(paragraphs[1:], paragraphDeliminator))
		if !usingTitle || (len(summary) > 0 && summary[len(summary)-1] != '.') {
			// overrides the schema value only if it's empty
			// keep the comment precedence when updating the package definition
			if summaryValue.Len() == 0 || isPackageObject {
				summaryValue.Set(reflect.ValueOf(summary))
			}
			if len(description) > 0 {
				if !descriptionValue.CanSet() {
					return errors.New("encountered object type with a summary, but no description")
				}
				// overrides the schema value only if it's empty
				// 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

View on GitHub (pinned to a58a4436a3)

Solutions

1. Ensure the schema object being annotated has a normal, exported Description field (i.e. use the library's own OpenAPI types rather than a custom replacement).
2. Remove or adjust proto comment annotations for the offending object so no description is attached to a non-settable target.
3. Update grpc-gateway to the latest patch version; this reflection path has had fixes around summary/description handling.
4. If embedding custom types, add a settable Description field of type string.

Example fix

// before
type mySchema struct {
    description string // unexported -> CanSet() == false
}
// after
type mySchema struct {
    Description string // exported -> settable
}

// ensure target object has a settable Description before attaching comments
v := reflect.ValueOf(obj).Elem()
d := v.FieldByName("Description")
if !d.IsValid() || !d.CanSet() {
    return fmt.Errorf("object %T has no settable Description", obj)
}

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

if err := applyTemplate(...); err != nil {
    if strings.Contains(err.Error(), "summary, but no description") {
        return fmt.Errorf("schema object lacks settable Description; check custom types: %w", err)
    }
    return err
}

When it happens

Trigger: Applying proto file/field comments to an OpenAPI schema object whose description property is not reflectively settable while a non-empty description exists — triggered during applyTemplate/template rendering when processing custom schema or extension types that lack a settable Description field.

Common situations: Using custom schema definitions/extensions with proto comments configured (e.g. openapiv2_field/schema options) where the target object struct does not expose a settable Description; library version drift between the generator's expected types and custom types.

Related errors

• no description nor summary property
• 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/8685812eed1da7f7. Report an issue: GitHub.