Repository navigation
Path-level parameters should be listed before operation-level parameters #7482
Description
Q&A (please complete the following information)
- OS: Windows 10
- Browser: Chrome, Firefox latest
- Method of installation: https://editor.swagger.io
- Swagger-UI version: 3.52.0
- Swagger/OpenAPI version: any
Content & configuration
Example Swagger/OpenAPI definition:
openapi: 3.0.0
info:
title: test
version: 0.0.0
paths:
/something/{id}:
parameters:
- in: path
name: id
required: true
schema:
type: string
get:
parameters:
- in: query
name: foo
schema:
type: string
responses:
'200':
description: okDescribe the bug you're encountering
In the API definition provided above, the /something/{id} path has path-level parameter id, plus the GET operation defines an additional parameter foo.
Swagger UI renders the path-level parameter id AFTER the operation-level parameters foo. This is often undesirable because path-level parameter list often contains in: path parameters (which are required), so it makes more sense to render path-level parameters first.
To reproduce...
Steps to reproduce the behavior:
- Paste the sample API definition into https://editor.swagger.io.
- Expand the operation.
Expected behavior
Parameter order is: id first, then foo.
Actual behavior
Parameter order is: foo, id.
Screenshots
Activity
mathis-m commentedon Sep 24, 2021
@hkosova @char0n this is not possible to do in swagger-ui. The fn
resolveSubtreereturns all parameters for an "method operation" by using swagger-jssubtree-resolver. There the spec is normalized, in this process the inherited parameters are appended to the "method operation parameters".With #6745 the grouping / sorting of parameters was implemented in swagger-ui, so prepending the inherited parameters in swagger-js instead will just solve the issue partially. With that said implementing the prepend of inherited parameters will result in having the first
in: typeat first place followed by the "method operation parameters" ofin: typeand so on.Example:
input inherited:
name: path1
name: query1
name: path2
input operation level:
name: path3
name: query2
result:
in: path
name: path1
in: path
name: path2
in: path
name: path3
in: query
name: query1
in: query
name: query2
char0n commentedon Sep 30, 2021
Hi all,
The new behavior suggested by @hkosova makes total sense (at least from my subjective perspective and others, that this has been discussed with).
@mathis-m I went through the #6745 and swagger-api/swagger-client#2256. I think we first need to define our expectations here. IMHO there is couple of things here that we need to decide and clarify.
Grouping
Grouping was introduced in #6745. We currently group Parameter Objects by
infield and retain the order that they were defined in (at least within the groups). That is the current behavior according to my understanding (correct me if I'm wrong).Sorting
We currently don't sort. It looks like we do because
Groupingcan appear to have that effect (again, correct me if I'm wrong).What do we really want?
IMHO it would be beneficial to define the expected behavior here to the last intricate detail. I'm putting here the first proposal that we can elaborate on.
Proposal 1 - Rendering according the the user intention
We trust the OAS definition author, that she knows what she's doing and that she's defined the order of the parameters in the order that she deemed appropriate. The user then expects the parameters to be rendered in the order as she defined them. And here comes the @hkosova proposal - parameters defined in Path Item Object get rendered before Operation level parameters. This means we have to get rid of current grouping algorithm. Please let me know what you think about this proposal.
Feel free to provide your own proposal of expected behaviors.
mathis-m commentedon Sep 30, 2021
@char0n I understand proposal 1, but as a user I see 2 usability points that need consideration.
Generated OAS
When the spec is generated one might not have control over the order.
1.1. Hope that the generator produces an logical order
1.2. Let swagger-ui be the tool that handels the order
Multiple different
in:types Path Level and Method level paramsThis will lead to the effect that one can not sort parameters by type via writing the spec, because the inherited params will occur before the method params. So this will actually take the possibility of sorting by type.
UX considerations that could fix this, is a table that can be sorted. Regarding #6661 and the points mentioned above I think there is the need of providing such functionality, either in automatic or manual way.
Regarding this issue there might also be the case where we support the raw order.
So this might need some UX input to find a solution: