Infer type from single allOf $ref
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 25.9k
- Forks
- 2.4k
- Avg merge
- 13h 10m
- Merged PRs (30d)
- 4
Description
Specifying the description for a property with a complex type is not allowed; for example, this is invalid because the description will be wiped out by $ref replacement:
FooOperationURL:
description: Endpoint that provides the ability to perform a foo operation
type: string
preview_url:
description: Endpoint at which to preview data
$ref: '#/components/schemas/FooOperationURL
The suggested (messy & ugly, IMO) workaround for this is to specify the type in an allOf clause:
preview_url:
description: Endpoint at which to preview data
allOf:
- $ref: '#/components/schemas/FooOperationURL
...but, ReDoc indicates that the type of preview_url in the latter case is merely string while in the former case it was much more usefully string (FooOperationURL).
I suggest that ReDoc treat a singular allOf $ref as the implied type of the property and therefore print that type hint in the documentation.
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 tracing ReDoc's schema rendering for a property using a singular allOf entry with a $ref, using the examples in this issue as the input cases. Done means the generated documentation shows the referenced schema's type hint, such as string (FooOperationURL), while preserving the property's description.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, typescript
- Domain
- api, documentation
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100