Open naesean opened 5 years ago
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
.
.
.
Would be great to either:
description
and summary
in the docs and link to the group operations with tags docdescription
and summary
with a link to something tracking the work to present the info better and link to the group operations tags docJust 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