Skip to content

Parameter description from gnostic.openapi.v3.property placed in schema instead of parameter level #182

@iwata

Description

@iwata

When using `gnostic.openapi.v3.property` annotation to add a description to a path parameter field, the generated OpenAPI places the description inside `parameter.schema.description` instead of `parameter.description`.

Current behavior:

parameters:
  - name: item_id
    in: path
    required: true
    schema:
      type: string
      description: "Item identifier"  # ← inside schema

Expected behavior (per OpenAPI 3.x spec):

parameters:
  - name: item_id
    in: path
    required: true
    description: "Item identifier"  # ← at parameter level
    schema:
      type: string

Impact:

  • OpenAPI linters (like Spectral) report `oas3-parameter-description` warnings
  • Incompatibility with tools expecting parameter-level descriptions

Reproduction:

Proto definition:

message GetItemRequest {
  string item_id = 1 [
    (buf.validate.field).required = true,
    (gnostic.openapi.v3.property) = {
      description: "Item identifier"
      example: {yaml: '"item123456789012345"'}
    }
  ];
}

Service definition:

service ExampleService {
  rpc GetItem(GetItemRequest) returns (GetItemResponse) {
    option (google.api.http).get = "/v1/items/{item_id}";
  }
}

Environment:

  • protoc-gen-connect-openapi: v0.22.0 (4fd2f0b)
  • buf: 1.61.0

Reference:
OpenAPI 3.0 Parameter Object Specification

Related Issue:
Similar issue was resolved for the `required` property in #65

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions