You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
When adding descriptions or titles for message fields that are not scaler value types, any title or description option is ignored, and replaced (if available) with the description of the message type.
This prevents proper context being provided for reusable items.
As an example, we have a date message that is re-used in multiple places.
// A fixed date without timezone information.
message Date {
// Year.
int32 year = 1;
// Month.
int32 month = 2;
// Date.
int32 day = 3;
}
And in the following message, a description is added to add context to the date value required:
// Details of document used to identify the traveler's identity.
message IdentityDetails {
IdentityDocument identityDocument = 1;
// The two digit ISO 3166 country code of the country of the travel document issuing authority.
string issuingCountry = 2;
// The two digit ISO 3166 country code of the traveler's nationality.
string nationality = 3;
// The number or other unique identifying reference of the traveler's document.
string documentNumber = 4;
// The date of birth as marked on the traveler's identity document.
Date dateOfBirth = 5;
// The gender as marked on the traveler's identity document.
Gender gender = 6;
// The issue date of the traveler's identity document.
Date issuedDate = 7;
// The expiry date of the traveler's identity document.
Date expiryDate = 8 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {title: "Nothing to see here", description: "The expiry date of the traveler's identity document."}];
}
But both the short-form comments, or the long form options are ignored when the JSON is generated:
"boardingIdentityDetails": {
"type": "object",
"properties": {
"identityDocument": {
"$ref": "#/definitions/boardingIdentityDocument"
},
"issuingCountry": {
"type": "string",
"description": "The two digit ISO 3166 country code of the country of the travel document issuing authority."
},
"nationality": {
"type": "string",
"description": "The two digit ISO 3166 country code of the traveler's nationality."
},
"documentNumber": {
"type": "string",
"description": "The number or other unique identifying reference of the traveler's document."
},
"dateOfBirth": {
"$ref": "#/definitions/ioDate",
"description": "The date of birth as marked on the traveler's identity document."
},
"gender": {
"$ref": "#/definitions/ioGender",
"description": "The gender as marked on the traveler's identity document."
},
"issuedDate": {
"$ref": "#/definitions/ioDate",
"description": "The issue date of the traveler's identity document."
},
"expiryDate": {
"$ref": "#/definitions/ioDate",
"description": "The expiry date of the traveler's identity document."
}
},
"description": "Details of document used to identify the traveler's identity."
}
I believe there should be a hierarchy of annotations, making it possible to override the referenced object description.
The text was updated successfully, but these errors were encountered:
When adding descriptions or titles for message fields that are not scaler value types, any title or description option is ignored, and replaced (if available) with the description of the message type.
This prevents proper context being provided for reusable items.
As an example, we have a date message that is re-used in multiple places.
And in the following message, a description is added to add context to the date value required:
But both the short-form comments, or the long form options are ignored when the JSON is generated:
I believe there should be a hierarchy of annotations, making it possible to override the referenced object description.
The text was updated successfully, but these errors were encountered: