Redocly / Redocly/redoc

Infer type from single allOf $ref

Open
#915 3 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Need review Type: Bug
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.