OpenAPI 3.1.0 support: SwaggerUI 5.6.1 incorrectly renders responses that do not have a content field defined.

[RyanSauter]

Q&A (please complete the following information)

• OS: Windows
• Browser: Chrome
• Version: 116.0.5845.180
• Method of installation: dist assets
• Swagger-UI version: 5.6.1
• Swagger/OpenAPI version: OpenAPI 3.1.0

Content & configuration

Example Swagger/OpenAPI definition:

openapi: '3.1.0'

info:
  title: Our API
  description: extended description of Our API
  version: 0.1.0

servers:
  - url: http://localhost
    description: included for completeness; not our actual url

tags:
  - name: Enterprise
    description: Operations with Enterprise ID

paths:
  /v0/enterprise/{id}:
    get:
      tags:
        - Enterprise
      summary: Get detailed info about an enterprise.
      description: |
        Returns detailed information for the specified Enterprise ID.

        This operation may *only* be performed by a **platform admin** or a 
        client with sufficient permissions.
      operationId: get_enterprise_detail
      parameters:
        - $ref: '#/components/parameters/traceIDHeader'
        - $ref: '#/components/parameters/enterpriseIDPath'
      responses:
        200:
          description: Successful request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnterpriseDetailResponse'
        404:
          description: No enterprise matching the requested ID could be found.
        500:
          description: An internal server error was encountered.

components:
  parameters:
    enterpriseIDPath:
      $ref: '#/components/parameters/idInPath'
      description: The Enterprise ID used to perform this request.
      example: "12422"

    idInPath:
      name: id
      in: path
      required: true
      schema:
        type: string

    traceIDHeader:
      name: X-Trace-Id
      in: header
      description: Optional UUID for log tracing
      required: false
      schema:
        type: string

  schemas:
    EnterpriseDetailResponse:
      title: Enterprise Detail Response
      type: object
      properties:
        id:
          type: string
          description: Unique ID for this enterprise.
          example: "3121"
        mfa_enforced:
          type: boolean
          description: Indicates whether MFA is enforced for this enterprise.
          example: true
        modules:
          type: array
          description: List of modules this enterprise is authorized to access.
          items:
            type: string
          example: [
            human_resources,
            project_management
          ]
        name:
          type: string
          description: The name of the enterprise.
          example: Kathy's Plumbing
        status:
          type: string
          description: Inidicates current status of this enterprise.
          enum:
            - offline
            - online
            - pending_deletion
            - unknown
          example: online

Swagger-UI configuration options:

SwaggerUI({
    url: "./openapi.yaml",
    urls: [
      {
        url: "./docs/our-api.yaml",
        name: "Our API"
      }
    ],
    dom_id: '#swagger-ui',
    deepLinking: true,
    defaultModelRendering: "model",
    defaultModelExpandDepth: 0,
    defaultModelsExpandDepth: -1,
    presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset
    ],
    plugins: [
        SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
})

Describe the bug you're encountering

We recently upgraded our SwaggerUI (unsure of our previous version) to v5.6.1 so that we could make use of OAS v3.1.0 in our spec documents. We also prefer to have our Swagger configured so that the Schema Models are rendered when the page is initially loaded, instead of the default to display the Example Value (i.e. configuration setting defaultModelRendering set to "model").

We are now encountering a rendering anomaly for our Responses that have no content. According to the OAS document, no content is an acceptable definition for a response object. (To clarify, by "no content response" we mean the definition of the response object does not include a content field; just a description field.)

What we see on the page in these cases is a warning (with a "screaming" emoji) that states "Could not render ModelWrapper, see the console." (Details are in the screenshots below.) If we change the configuration to initially display the Example Value (swagger default behavior), we no longer see the warning, but we still get a rendered code block where we shouldn't see anything at all (just the text from the description field for the response object). We cannot reproduce this specifically in the Swagger Editor (https://editor-next.swagger.io/) as we cannot configure the initial rendering as stated above. However, you can see that there are code blocks being rendered for the empty content responses, which should not be happening.

To reproduce...

Steps to reproduce the behavior:

1. Use the included YAML content and the swagger configuration (both above in this post) to render a Swagger spec page.
2. Observe in the Responses section that both 404 and 500 responses display the warning message.
3. Change the configuration defaultModelRendering to "example" and re-render the Swagger spec page.
4. Observe in the Responses section that both 404 and 500 responses display a code block with a single line: "string"

Expected behavior

In the described scenario, we would expect that a "no content response" would not attempt to render any object below the text from the description field in the response object definition. This is the behavior that was present in older versions (at least v4.x.x?) of the Swagger UI files.

Screenshots

Example of "no content responses" (404, 500) where defaultModelRendering is set to "example" (default Swagger behavior):

Example of "no content responses" (404, 500) where defaultModelRendering is set to "model":

Screen grab of the console:

Additional context or thoughts

• I am unsure about the previous version of the Swagger-ui files we were using. I was not the developer that initially built this for our use. We were using OAS 3.0.2, so it is possible that we were using Swagger-ui v4.x.x previously.
• We very much would prefer to set the defaultModelRendering configuration to "model", as we like having developers see the Schema definitions on initial view of the page. And we don't like staying on the "example" default rendering as it still looks unprofessional, even if it isn't a warning message; the code blocks being rendered for empty content look like we are missing information when we are not.

[LucsFreitas]

I also have the same problem in v5.7.2, however, apparently it has no connection with the swagger-ui version. The problem occurs when I set the openapi: 3.1.0. In 3.0.x and earlier, the response is displayed without body correctly.

[RyanSauter]

That is good observation, one that I had not encountered.
Unfortunately, I still think it is a rendering issue within swagger-ui. We need some of the features presented in OAS 3.1.0, and only swagger-ui v5.x.x will render that version of OAS.

[outdooracorn]

I've also noticed this issue with v5.9.4. However, I don't get the screaming emoji warning. Instead, an example value of "string" even though no example was specified.

"PreconditionFailedError": {
    "description": "The condition defined by a conditional request header is not fulfilled"
},

[Danstiv]

I also have similar problem.

I have a response without a schema, but SwaggerUI tries to show it and I end up getting the same error with emoji.

I can reproduce that with this schema:

{
    "openapi": "3.1.0",
    "info": {
        "title": "test",
        "version": "0.1.0"
    },
    "paths": {
        "/test/": {
            "get": {
                "summary": "Get",
                "operationId": "get_test__get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/octet-stream": {}
                        }
                    }
                }
            }
        }
    }
}

When I open SwaggerUI 5.9 with defaultModelRendering set to model, the above problem happens.

Should i open separate issue for that case?

[char0n]

Hi everybody,

I can confirm that this is bug related to OpenAPI 3.1.0 exclusively.

The issue is in two plugins:

json-schema-2020-12-samples

When samples are being generated and neither schema nor example override is provided, the sample generator should return undefined. Instead what it does is that it type cast the schema provided as undefined to empty schema {}, which eventually generates the "string" sample.

oas31

In this plugins afterLoad function we're not overriding following JSON Schema 5 sample generation function with JSON Schema 2020-12 ones:

• getJsonSampleSchema
• getYamlSampleSchema
• getXmlSampleSchema
• getSampleSchema

This results in using JSON Schema 5 sample generator for JSON Schema 2020-12, which is source of another issues.

---

Both issues have been addressed in #9664
@Danstiv your issue has been addressed as well.

[char0n]

Released in https://github.com/swagger-api/swagger-ui/releases/tag/v5.11.10