Swagger UI default layout for externalDocs can't handle long URLs #7305
Description
Q&A (please complete the following information)
- OS: macOS, Linux (Ubuntu 20.10)
- Browser: chrome
- Version: 91.0.4472.69 (but been occuring for many versions)
- Method of installation: maven central (as a dependency of springdoc)
- Swagger-UI version: 3.47.1 (also tested 3.49.0)
- Swagger/OpenAPI version: v3
Content & configuration
This is a fragment for a larger doc which contains all our API definitions, this specific issue relates to the way external Doc links are handled with tags:
Example Swagger/OpenAPI definition:
# your YAML here{
"tags": [
{
"description": "The operational administration services support the management of OMAG Server instances. This includes starting and stopping the
servers as well as querying and changing their operational state.",
"externalDocs": {
"description": "Further information",
"url": "https://egeria.odpi.org/open-metadata-implementation/admin-services/docs/user/operating-omag-server.html"
},
"name": "Administration Services - Operational"
},
]
}
Swagger-UI configuration options:
Using
swagger-ui.path=/swagger-ui.html
swagger-ui.displayRequestDuration=true
swagger-ui.tagsSorter=alpha
swagger-ui.operationsSorter=alpha
swagger-ui.docExpansion=none
swagger-ui.layout=StandaloneLayout
(Also tried without specifying layout, and also setting to BaseLayout, but the issue occurs in each case)
Describe the bug you're encountering
When an 'externalDocs' link is added for a tag, and a medium length URL is used, the formatting of the entire document is
poor - leading to detailed description being a few characters per line.
This image offers an example:
To reproduce...
Steps to reproduce the behavior:
Just load the API doc scrollling down it's easy to see lots of very poorly formatted text
Expected behavior
A better layout by default that renders the external link reasonably - probably not within a single table cell, and
avoiding making the rest of the doc unreadable
Screenshots
see above