[FR] Do not show `(from schema)` if example provided explicitly

[IanVS]

Is your feature request related to a problem?

It's a minor thing, but if I provide an example key to the response schema, I see that it's used in the default Example (from schema) tab, which is awesome. But it would be even more awesome of the "from schema" wasn't included, since it's not generated data but explicit values that I've filled out.

Describe the solution you'd like

Detect the presence of a responses.X.content.X.schema.example, and if found, just call the example Example instead of Example (from schema)

Additional context

Here's what I'm seeing currently:

[sserrata]

Hi @IanVS, "from schema" is akin to saying the example if inferred from the schema properties, whether each property has an example or default defined or not.

That said, when I think of what an "explicit" example is, I think of example or examples that can be statically defined, which I believe is different from the inferred "Example (from schema)".

Hope I explained that correctly 😅. I am open to dropping the "from schema" label but I'd also like to prevent possible tab label/value collisions.

[IanVS]

Does it make a difference that I'm not setting examples on properties, but rather at the top of schema?

          schema:
            type: object
            required:
              - data
              - metadata
            properties:
              data:
                type: array
                items:
                  $ref: '../../schemas/AuditLog.yaml'
              metadata:
                $ref: '../../schemas/PaginationMetadata.yaml'
            example:
              data:
                id: log-F3TTIDMKZH5XFH37RTRLIP3TOA
                organizationID: org-F63A24JGCLJV3ZEUTLCBISGETA
                timestamp: 2023-02-15T13:59:09.828868Z
                actor:
                  id: dnkey-DXALSPQONG7H45QZAVTPRDMAPU
                  name: example api key
                  type: apiKey
                target:
                  id: role-LO4SPDSWTZNJC676WFCZKUB3ZQ

[sserrata]

Does it make a difference that I'm not setting examples on properties, but rather at the top of schema?

I believe it does, because schema.example or schema.examples are static and taken at face value, not as strongly tied to the actual schema/properties. Also, the "from schema" example can be generated/inferred even without any example/default values defined, in which case it falls back to the data type. I guess the difference is "100% inferred" vs "inferred with some help". Thoughts?

[IanVS]

Yeah I agree. Since I'm using the schema.example and the example will be shown as-written, that's why I would expect that from schema is not included in the tab.

[sserrata]

@IanVS, upon second inspection, I believe your example may be defined at the wrong indention level. I believe it should be at the same level as schema.

[IanVS]

If I do that, then it is used as an extra example next to Example (from schema), which also isn't what I want. I want it to be used instead of the auto-generated schema example, and putting it there seems to accomplish that. As for it being valid openAPI, it at least passes the redocly lint tool. 🤷

[sserrata]

Ah ok...I trust redocly but I wonder if they may be applying the same linter rule to both request and response schemas?

Check out the examples in the official OpenAPI docs: https://swagger.io/docs/specification/adding-examples/

If I am interpreting the docs correctly, example should be at the same level as schema under the response definition. You see both the "from schema" tab and the "Example" tab because the "from schema" tab is rendered regardless of whether example or examples is defined. I think you may be asking if there's a way to suppress the "from schema" tab if example or examples is defined?

[IanVS]

I think you may be asking if there's a way to suppress the "from schema" tab if example or examples is defined?

Yes, I think that would solve my needs as well. :+1:

[sserrata]

adding to roadmap with the goal of either: allowing users to suppress the generated/inferred schema or programmatically suppressing if example(s) exist.