swagger-api / swagger-api/swagger-ui

Issue with Rendering XML Examples

Open
#11,023 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Q&A (please complete the following information)
  • OS: macOS
  • Browser: Google chrome
  • Version: 151.0.7922.138 (Official Build) (arm64)
  • Method of installation: npm
  • Swagger-UI version: 5.20.5
  • Swagger/OpenAPI version: OpenAPI 3.0
Content & configuration

Example Swagger/OpenAPI definition:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Data Upload",
    "version": "1.22.1"
  },
  "security": [
    {
      "OAuth2": ["{x_pname}.InboundProcessing"]
    }
  ],
  "paths": {
    "/idocinbound": {
      "post": {
        "security": [
          {
            "OAuth2": ["{x_pname}.InboundProcessing"]
          }
        ],
        "requestBody": {
          "content": {
            "application/xml": {
              "schema": {
                "oneOf": [
                  { "$ref": "#/components/schemas/Schema1" },
                  { "$ref": "#/components/schemas/Schema2" }
                ]
              },
              "examples": {
                "example1": {
                  "$ref": "#/components/examples/XmlExample1"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://example.com/token",
            "scopes": {
              "{x_pname}.InboundProcessing": "Inbound Processing"
            }
          }
        }
      }
    },
    "schemas": {
      "Schema1": {
        "type": "object",
        "properties": {
          "data": { "type": "string" }
        }
      },
      "Schema2": {
        "type": "object",
        "properties": {
          "data": { "type": "string" }
        }
      }
    },
    "examples": {
      "XmlExample1": {
        "value": "<?xml version=\"1.0\"?><Root><Data>Test</Data></Root>"
      }
    }
  }
}

Swagger-UI configuration options:

SwaggerUI({
      spec: apiSpec,
      dom_id: '#api-ui-container',
      defaultModelRendering: 'model',
      showExtensions: true,
      deepLinking: true,
      plugins: [DisableTryItOutPlugin],
      onComplete(): void {
        setTimeout(() => that.swaggerUiOnComplete(that), 500);
      }
});
Describe the bug you're encountering

In Swagger-UI v5.20.5, XML examples provided in our OpenAPI documentation file are not rendered properly. Specifically, characters such as '<' are converted into '<', '>' are converted to '>' and similarly for other XML special characters. This makes the XML examples harder to understand and unusable in certain circumstances.

To reproduce...
  1. Go to POST /idocinbound
  2. Click on application/xml option for request body parameters.
  3. Observe the example value.
Expected behavior

The XML request payload examples should render properly, showing XML characters (<, >, etc.) without conversion into HTML entities (such as <, >).

Screenshots
Image
Additional context or thoughts

An initial analysis points that this issue is reproducible if we have oneOf or anyOf.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the issue in Swagger UI v5.20.5 using the POST /idocinbound request body, the application/xml media type, and the oneOf schema with the referenced XML example. Start by tracing the example-rendering path used by defaultModelRendering: 'model' and compare behavior with oneOf or anyOf; done means XML examples display literal < and > characters rather than HTML entities.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
frontend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.