-
Notifications
You must be signed in to change notification settings - Fork 8.9k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Path Summary and Description Not Rendered #5653
Comments
Thanks for the report, @naesean. You're correct in saying it's not rendered. This was an addition in OpenAPI 3.0, but it's one that doesn't really work well with how Swagger UI renders. Since the operations are grouped based on tags (which is what the specification intends), and a single operation can appear in multiple tags, or otherwise, separate operations from a single path can appear under different tags, there's no easy way to present that information. It's a bit of a UX challenge in terms of how to present it. You're welcome to suggest ideas though. |
Rearrange the order of display to be endpoint first, with summary and description, then the methods. Tags could be treated as filters instead of part of the taxonomy. |
Unlikely to happen, though we may consider it. Tags are intended for grouping of operations, not filters. |
May create a pull request for this, but, for those like me that wanted some way of documenting an endpoint that roughly correlates to an entity and it's associated operations (looks like that was what @naesean's intention was). Here's what may be the start of solution/workaround: A Google search got me Grouping Operations with Tags A sample of how this might look like: .
.
tags:
- name: meta
description: operations about the service, itself (e.g. whether the service is up)
paths:
/api/meta/ready:
get:
tags:
- meta
.
.
.
|
Just ran into this limitation as well. Trying to create robust documentation for our API but path description, although supported by the openAPI 3.0 spec, is not as useful if won't be rendered by Swagger UI. |
Q&A (please complete the following information)
Content & configuration
https://app.swaggerhub.com/apis/vacasa5/Simple/1.0.0
Example Swagger/OpenAPI definition:
Swagger-UI configuration options:
Describe the bug you're encountering
Under the /paths/pathName the spec allows a summary and description that applies to the entire endpoint. Those values are not rendered.
To reproduce...
Steps to reproduce the behavior:
Add a summary and description under a path
Expected behavior
Swagger UI would render the summary and description in a way that made it clear it applied to all operations
Screenshots
Additional context or thoughts
The text was updated successfully, but these errors were encountered: