Field descriptions ignored and overwritten by referenced objects
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 25.9k
- Forks
- 2.4k
- Avg merge
- 13h 10m
- Merged PRs (30d)
- 4
Description
Take the case of the swagger below where descriptions have been added to give context to multi-purpose objects such as Date.
"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."
}
When rendered, these descriptions (and also titles) are ignored and referenced object's descriptions are used instead.
Should there not be a hierarchy, making it possible to override a referenced object's title and description?
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the provided Swagger example in Redoc and trace how referenced schemas supply titles and descriptions during rendering. Add coverage for property-level overrides and verify that local titles and descriptions take precedence over those on referenced objects.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, typescript
- Domain
- api, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100