-
Notifications
You must be signed in to change notification settings - Fork 9.2k
Description
Q&A
- OS: Windows / Linux (reproduced on both)
- Browser: Chrome, Firefox
- Version: Latest stable versions
- Method of installation: dist assets, npm
- Swagger-UI version: Tested on multiple versions including 4.x.x
- Swagger/OpenAPI version: OpenAPI 3.0.3
Content & configuration
Example Swagger/OpenAPI definition:
openapi: 3.0.3
info:
title: Test API
version: 1.0.0
paths:
/test:
post:
summary: Test endpoint
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
age:
type: integer
example:
name: John Doe
age: 30
responses:
'200':
description: OK
Swagger-UI configuration options:
SwaggerUI({
url: "/v3/api-docs",
dom_id: "#swagger-ui"
});
Describe the bug you're encountering
When adding an example
to the full request schema (i.e. requestBody.content.application/json.schema.example
), Swagger UI renders the example incorrectly in the "Schema" section of the UI.
Instead of displaying a clean JSON object, it inserts OrderedMap
prefixes before keys, like this:
{
"OrderedMap { name": "John Doe",
"age": 30
}
This is not part of the OpenAPI definition. The JSON returned from /v3/api-docs
is fully valid and does not contain OrderedMap
or any such artifacts. The issue appears to be internal to Swagger UI's rendering logic.
To reproduce...
Steps to reproduce the behavior:
- Define a request body schema and include an
example
at the top level of the schema - Serve it using Swagger UI
- View the endpoint in the UI and scroll to the request's "Schema" section
- Observe that the example includes unexpected
OrderedMap
strings
Expected behavior
The example should be rendered exactly as defined, without any internal object type names like OrderedMap
. Expected output:
{
"name": "John Doe",
"age": 30
}
Screenshots
(Optional: add screenshots if available)
Additional context or thoughts
We maintain public documentation for dozens of API clients. This issue causes confusion, as consumers believe that OrderedMap
is something they need to include in requests. This leads to avoidable support requests and distrust in the docs.
Swagger UI should render examples exactly as defined, especially for request bodies. We consider this a major bug and would greatly appreciate a fix or workaround in a future release.
Happy to provide a full reproduction repo if needed.
Thanks!