redocly-cli icon indicating copy to clipboard operation
redocly-cli copied to clipboard

Bundler Does Not Resolve Discriminator Mapping Values

Open its-hammer-time opened this issue 2 weeks ago • 9 comments

Describe the bug

When using the --dereferenced argument with the Redocly CLI bundler, references found under the discriminator mapping section are not resolved and therefore may be broken. For example, given the schema below, the redocly bundler would appropriately resolve the references under allOf and add them to the bundled result, but the mapping references would remain as-is. Depending on the values of the mapping references, those references may no longer exist (i.e. if the bundled file is in a different location).

discriminator:
  propertyName: type
  # These are not dereferenced
  mapping:
    VAL_1: ../values/val1.yaml
    VAL_2: ../values/val2.yaml
# These are dereferenced
allOf:
  - $ref: ../values/val1.yaml
  - $ref: ../values/val2.yaml

To Reproduce

Commands I ran:

redocly --version
1.16.0

redocly bundle --dereferenced openapi.yaml --output bundled.yaml

I've provided an example repo which you can use to reproduce this, but it's really easy to setup a fresh example as well. You need something like the following structure:

/
  openapi.yaml
  example/
    my-example.yaml
  values/
    val1.yaml
    val2.yaml

Let's say I bundle the setup above and I place my bundled folder at the root (next to openapi.yaml). If the my-example.yaml has references to ../values/val1.yaml then the resulting bundled file will still have ../values/val1.yaml which is no longer a valid location since it should have been moved to ./values/val1.yaml.

example.zip

I imagine the example your company has on their docs would also run into this issue if you bundle with a dereferenced spec. In the example with $refs you can see they have ../components/..... which may no longer be valid locations since the bundled spec can be output anywhere.

Expected behavior

According to the official OpenAPI 3.1.0 documentation, the mapping section is "An object to hold mappings between payload values and schema names or references". If I'm using the Redocly CLI to dereference while bundling, then the CLI should attempt to resolve these values much like it does when it sees the $ref keyword.

This isn't from your code, but we use the Python openapi-core package which internally uses openapi-schema-validator. For their implementation of discriminators, they do attempt to resolve the file references which is how we noticed this behavior.

Logs

N/A

OpenAPI description

Here's the openapi.yaml file I used in my example.zip folder above.

openapi: 3.1.0
servers:
  - url: http://localhost:8080
info:
  title: Example Service
  version: 1.0.0
paths:
  /test:
    get:
      responses:
        default:
          content:
            application/json:
              schema:
                type: object
                properties:
                  test:
                    type: string
                    example: "test"
components:
  schemas:
    Example:
      $ref: example/my-example.yaml

Redocly Version(s)

1.16.0

Node.js Version(s)

v18.17.1

Additional context

N/A

its-hammer-time avatar Jun 28 '24 17:06 its-hammer-time