Downloading JSON renders empty descriptions for some properties

[monica-m-ps]

Describe the bug When downloading the JSON, some descriptions aren't rendered at all. But they look fine on the site. (Maybe these descriptions are nested inside nested?)

Expected behavior Descriptions shouldn't be empty

Minimal reproducible OpenAPI snippet(if possible)

  customerEmail:
    nullable: true
    oneOf:
      - $ref: ./PaymentIntentConfigCustomerEmail.yaml
    description:   
      $ref: ../../../prose/parameters/customerEmail.md

paymentIntentConfigCustomerEmail looks like:

type: object
additionalProperties: false
title: PaymentIntentConfigCustomerEmail
description: ''
properties:
  collectionRequired:
    type: boolean
    description:    
      $ref: ../../../prose/parameters/collectionRequired.md
    default: false

Screenshots

Additional context

Can someone please help me here?

[romanpryshliak]

Hello @monica-m-ps,

I noticed that within the snippets provided, two properties customerEmail and collectionRequired have descriptions matching what's shown in the screenshots. I have also noticed that the paymentIntentConfigCustomerEmail schema lacks a description in both the snippet and the screenshot.

Based on this, could you please specify which description exactly is missing after the file is downloaded? If there's publicly accessible documentation showcasing this issue, could you kindly provide a link to it?

[jeremyfiel]

@monica-m-ps this is similar to your last post https://github.com/Redocly/redoc/issues/2431

The oneOf and description are siblings and are not allowed in OAS 3.0.x. If you want to use both properties you need to modify the schema to use allOf to encapsulate them.

  customerEmail:
    nullable: true
    allOf:
      - oneOf:
        - $ref: ./PaymentIntentConfigCustomerEmail.yaml
      - description:   
        $ref: ../../../prose/parameters/customerEmail.md

[jeremyfiel]

@monica-m-ps can this be closed?

[monica-m-ps]

Yes please. Sorry there are still discussions going on within the team here. @romanpryshliak : This is currently live on docs.dojo.tech/api.

@jeremyfiel Thanks for this solution. If I'll need to ask anything else, I'll post it again. Thank you!

[jeremyfiel]

@monica-m-ps Are you still having some issue with the description populating? I don't see it on the link you provided.

I think I misunderstood your usage of oneOf. You should be able to get the description without the oneOf.

 customerEmail:
    nullable: true
    allOf:
      - $ref: ./PaymentIntentConfigCustomerEmail.yaml
      - description:   
          $ref: ../../../prose/parameters/customerEmail.md

[monica-m-ps]

Descriptions populated are fine. When you download the JSON, that's when some descriptions appear to be empty.