OpenAPI: Add support for query string parameters #1378
Merged
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adds the JSON:API query string parameters (include, filter, sort, page, fields) to OpenAPI schema generation, but in a pretty unstructured way. This is because the parameter names depend on the available relationships and resource types. For example:
filter[owner.assignedTodoItems]
andfields[people]
. It would not only explode the number of combinations (making SwaggerUI pretty unusable and generating many method parameters in the NSwag C# client), but it is not even possible because it leads to potential infinite recursion. For example:?filter[node.parent.parent.parent...]
.So instead the parameters are defined as an unstructured map of key/value pairs. Here's what it looks like in SwaggerUI:
SwaggerUI requires specifying the query string as a JSON object. For example, entering:
gets translated by SwaggerUI to:
In the generated C# client, you pass query strings as below:
If a controller is decorated with
[DisableQueryString(JsonApiQueryStringParameters.All)]
, we could hide the query string from OpenAPI. I didn't implement that, because the information is hard to obtain and it's a corner case. And when users decide to add their own query string parameters, it would incorrectly hide the possibility of providing them.Closes #1058
Fixes #1374
Fixes #1375
Fixes #1376
QUALITY CHECKLIST