Skip to content
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

Swagger generation includes query parameters in the request mapping path #34

Closed
kunal-pmj opened this issue Jan 24, 2019 · 2 comments
Closed

Comments

@kunal-pmj
Copy link

kunal-pmj commented Jan 24, 2019

The swagger specifications generated from this tool are not Swagger 2.0 compliant. There are few APIs whose Query Parameters are appended to the Request Mapping URL.
As per Swagger 2.0 and 3.0 specifications Parameters can be of following types and they should be defined in the Parameters section of operations for every path or at the path.

path parameters, such as /users/{id}
query parameters, such as /users?role=admin
header parameters, such as X-MyHeader: Value
cookie parameters, which are passed in the Cookie header, such as Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCU

@kunal-pmj
Copy link
Author

One such example would be following REST API.
"/com/vmware/cis/tagging/tag/id:{category_id}?~action=list-tags-for-category": { "post": {
To make it Swagger 2.0 complaint. The query parameter should be removed from request mapping path and moved to the the parameter section.
{ "name": "~action", "in": "query", "description": "~action=list-tags-for-category", "required": true, "type": "string", "enum": [ "list-tags-for-category" ] }
This way the the parameter can be made required with only one possible value

@karaatanassov
Copy link
Collaborator

This is artifact of the underlying APIs there is no option in the generator to change that reality.

Swagger 2.0 actually defined the path as URI template. As per URI template RFC the path templates can contain query parameter expansions including fixed expansions.

https://www.rfc-editor.org/rfc/rfc6570#section-3.2.9

The problem is more with OpenAPI 3 schema as that does not define way for such fixed query parameters

OAI/OpenAPI-Specification#164

Anyway there is little choice in this project to do anything about these issues.

@karaatanassov karaatanassov closed this as not planned Won't fix, can't repro, duplicate, stale Sep 30, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants