Redocly / redocly-cli

⚒️ Redocly CLI makes OpenAPI easy. Lint/validate to any standard, generate beautiful docs, and more.
https://redocly.com/docs/cli/
MIT License
849 stars 129 forks source link

ContentSchema and bundling #1598

Open onavratil-monetplus opened 1 week ago

onavratil-monetplus commented 1 week ago

Describe the bug

The bundle utility does not recognize references within contentSchema

For example:

myData:
  type: string
  contentEncoding: base64
  contentMediaType: application/json
  contentSchema:
    $ref: some-model.yaml

The resulting bundled file will still contain the original $ref: some-model.yaml - the reference will neither be unfolded nor added to components/schemas or so.

To Reproduce Steps to reproduce the behavior:

This OpenAPI file(s)

openapi: 3.1.0
tags:
  - name: test
info:
  title: Bundle Sample
  version: '0.1.0'
  description: |
    Sample API
  contact:
    name: Ondřej Navrátil
    email: onavratil@monetplus.cz
servers:
  - url: '127.0.0.1'
    description: localhost
paths:
  /test-endpoint:
    get:
      summary: Sample with Ref
      operationId: post-something
      description: |-
        xxx.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
                contentEncoding: base64
                contentMediaType: application/json
                contentSchema:
                  $ref: some-model.yaml
      tags:
        - test

The contents of some-model.yaml are irrelevant (redocly will not do anything with the file), but to make the original schema valid, lets consider it contains something like this:

type: string
description: Referenced model.
  1. Run this command with these arguments...
    $ redocly bundle sample-api.yaml
  2. See error
    bundling sample-api.yaml...
    openapi: 3.1.0
    info:
    title: Bundle Sample
    version: 0.1.0
    description: |
    Sample API
    contact:
    name: Ondřej Navrátil
    email: onavratil@monetplus.cz
    servers:
    - url: 127.0.0.1
    description: localhost
    tags:
    - name: test
    paths:
    /test-endpoint:
    get:
      summary: Sample with Ref
      operationId: post-something
      description: xxx.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
                contentEncoding: base64
                contentMediaType: application/json
                contentSchema:
                  $ref: some-model.yaml
      tags:
        - test
    components: {}
    📦 Created a bundle for sample-api.yaml at stdout 18ms.

    The $ref stays there, but is not unfolded into components

Expected behavior

$ref will be resolved and bundled

Redocly Version(s)

1.16.0

Node.js Version(s)

$ nodejs --version
v10.19.0

Additional context

These keywords are part of 2019 draft and OAS 3.1.0 references 2020-12 draft of JSON schema; thus compliance with OAS 3.1, which redocly proclaims, should include this behavior.

I know that redoc as such does not visualize contentSchema in the generated html, but e.g. contentMediaType and contentEncoding are somehow supported. Moreover, the resulting bundled specs (which is also downloadable from the standalone html) is formally invalid because of the missing reference, and thus may cause problems with other tooling that resolve and utilize contentSchema references.

jeremyfiel commented 1 week ago

The typing is not defined in the Oas3_1.ts of the core package. You're welcome to send a PR to add this keyword to the Schema type definition after this line https://github.com/Redocly/redocly-cli/blob/2bfef43b8ab0656141fa52977bf8303cd323aa96/packages/core/src/types/oas3_1.ts#L171-L172

contentSchema: 'Schema',