Referring object tamper other objects through referenced one

Question

Referring object tamper other objects through referenced one

vZ2JEZsZW opened this issue 10 months ago · comments

description and examples of referring objects discarded in favor of values spreading from other objects referring same target.

Steps to Reproduce:

# file2.yaml
referenced: { type: string }
object:
    allOf:
        -   type: object
            properties:
                AAAAA:
                    $ref: '#/referenced'
                    description: AAAAA
                    examples: [AAAAA]
                BBBBB:
                    $ref: '#/referenced'
                    description: BBBBB
                    examples: [BBBBB]

# file1.yaml
paths:
    /operation:
        post:
            summary: operation
            requestBody:
                required: true
                content:
                    application/json:
                        schema: {$ref: 'file2.yaml#/object'}
            operationId: operationId
            security: [ ]
servers: [ url: 'http://example.com' ]
openapi: 3.1.0
info:
    title: Test
    version: version

Resulting documentation: BBBBB gets irrelevant description and examples from AAAAA

Version used: 7.13.1

Matt Murphy · Answer 1 · Sat Nov 18 2023 01:29:41 GMT+0800 (China Standard Time)

Here's another example of the problem:

openapi.yaml:

openapi: 3.1.0
info:
  title: Test
  version: version
paths:
  /operation:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                AAAAA:
                  $ref: 'referenced.yaml'
                  description: AAAAA
                  examples:
                    - AAAAA
                BBBBB:
                  $ref: 'referenced.yaml'
                  # If description is commented out, it's displayed as AAAAA
                  description: BBBBB
                  # Example is displayed as AAAAA
                  examples:
                    - BBBBB

referenced.yaml:

title: referenced
type: string

In this example the response body is inline rather than ref'ed and does not include the allOf to show combiners are not part of the problem. referenced is still in its own file and the problem does not appear to exist if it's inline or a ref to a schema in the same file in the components section.

Results in:

Brenda Rearden · Answer 2 · Thu Nov 30 2023 06:02:20 GMT+0800 (China Standard Time)

@vZ2JEZsZW I am currently troubleshooting this and had a question: were you using elements dev portal when encountering this issue?
I am not able to reproduce in elements with the example provided due to elements using a single file and not two separate files.

vZ2JEZsZW · Answer 3 · Thu Nov 30 2023 15:53:26 GMT+0800 (China Standard Time)

were you using elements dev portal when encountering this issue? I am not able to reproduce in elements with the example provided due to elements using a single file and not two separate files.

I believe it's "stoplight elements" and in my case the spec was split in several files so was the minimal reproducible example I extracted. What follows is an html page which exhibits described behavior.

page.html

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>api</title>
    <script src="https://unpkg.com/@stoplight/elements@7.13.1/web-components.min.js"></script>
    <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements@7.13.1/styles.min.css">
</head>
<body>
    <elements-api apiDescriptionUrl="file1.yaml" router="hash" />
</body>
</html>

Yamls are same files from original post repeated for completeness.

file1.yaml

paths:
    /operation:
        post:
            summary: operation
            requestBody:
                required: true
                content:
                    application/json:
                        schema: {$ref: 'file2.yaml#/object'}
            operationId: operationId
            security: [ ]
servers: [ url: 'http://example.com' ]
openapi: 3.1.0
info:
    title: Test
    version: version

file2.yaml

referenced: { type: string }
object:
    allOf:
        -   type: object
            properties:
                AAAAA:
                    $ref: '#/referenced'
                    description: AAAAA
                    examples: [AAAAA]
                BBBBB:
                    $ref: '#/referenced'
                    description: BBBBB
                    examples: [BBBBB]