swagger-api / swagger-api/swagger-ui
Issue with Rendering XML Examples
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...
- Go to POST /idocinbound
- Click on application/xml option for request body parameters.
- 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
Additional context or thoughts
An initial analysis points that this issue is reproducible if we have oneOf or anyOf.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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