ReDoc fails to expand JSON Schema refs in examples

[MateusAzevedo]

Related to #311 and #380

I'm using external schema and example files to reuse them in multple operations. ReDoc correctly render example code for the first operation, but fails to render subsequent ones, rendering something like this:

As @vegyraupe commented in #380:

The problem occurs when the same external reference is being used twice. This results in bundle to only include it once and returning a relative reference instead of the dereferenced object.

You asked for a reproducible example, so a created this Gist to help.

I tested the example spec with "redoc-cli serve", "redoc-cli bundle" and "speccy serve", all result in the same problem.
In the final bundled spec file, the schema and example code are included in the first operation, but the other ones have just a reference to the first operation:

"responses": {
    "200": {
        "description": "OK",
        "content": {
            "application/json": {
                "schema": {
                    "$ref": "#/paths/~1cities/post/responses/201/content/application~1json/schema"
                },
                "example": {
                    "$ref": "#/paths/~1cities/post/responses/201/content/application~1json/example"
                }
            }
        }
    }
}

As you can see, both schema and example have a reference to the first operation. ReDoc can render the schema for all operataion (it follows the $ref) but don't do the same for the example.

[RomanHotsiy]

Your spec is incorrect according to the OpenAPI 3.0 spec.

example field of Media Type Object can't be a $ref - it is direct example value. (the fact ReDoc dereferences it for the first operation is, in fact, ReDoc bug which I don't think I can fix in short term)

In order to use $ref for example values use examples field. It supports $ref and ReDoc will handle it properly in the upcoming release (I just implemented it).

Here is the updated gist: https://gist.github.com/RomanGotsiy/29152ff5a4da68dbb49131eaaf347530

Closing this issue. Feel free to continue the discussion here.

The new ReDoc version is coming tomorrow.

[alexgmin]

Your spec is incorrect according to the OpenAPI 3.0 spec.

example field of Media Type Object can't be a $ref - it is direct example value. (the fact ReDoc dereferences it for the first operation is, in fact, ReDoc bug which I don't think I can fix in short term)

This was also a point of contention in Swagger-UI. swagger-api/swagger-ui#4924 (comment)

While I would prefer that example was rendered, I don't mind if it works in examples as long as it works.

[RomanHotsiy]

It will work using externalValue in examples once I release a new version. This happens a bit later today.

[RomanHotsiy]

v2.0.0-rc.4 has been just released with the support of externalValue

[Okobiti]

@RomanHotsiy the gist you provided https://gist.github.com/RomanGotsiy/29152ff5a4da68dbb49131eaaf347530 seems to have been deleted. Any chance you can provide an example of how examples and $ref should work with redoc? I'm using version 2.0.0-rc.18, and having some issues displaying it.

[jaspersorrio]

TL;DR

It works if you use examples instead of example

# DOESN'T WORK ×
      example:
        title: Test & Measure
        children:
          - $ref: "#/components/schemas/SubCategory/example"

# WORKS ✓  (Changed "example" -> "examples") 
      examples:
        title: Test & Measure
        children:
          - $ref: "#/components/schemas/SubCategory/example"

[dpkirchner]

@jaspersorrio Would you mind including that in the context of the original gist? I'm not sure where to add that to get it to render properly in ReDoc.