-
Notifications
You must be signed in to change notification settings - Fork 40
Open
Description
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 schemaExpected behavior (per OpenAPI 3.x spec):
parameters:
- name: item_id
in: path
required: true
description: "Item identifier" # ← at parameter level
schema:
type: stringImpact:
- 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
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
No labels