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

OpenAPI: Add support for query string parameters #1378

Merged
merged 7 commits into from
Oct 30, 2023

Conversation

bkoelman
Copy link
Member

@bkoelman bkoelman commented Oct 30, 2023

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] and fields[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:

image

SwaggerUI requires specifying the query string as a JSON object. For example, entering:

{
  "sort": "name",
  "filter": "equals(name,'some')"
}

gets translated by SwaggerUI to:

image

In the generated C# client, you pass query strings as below:

NodeCollectionResponseDocument response = await apiClient.GetNodeCollectionAsync(new Dictionary<string, string?>
{
    ["sort"] = "name",
    ["filter"] = "equals(name,'some')"
});

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

@codecov
Copy link

codecov bot commented Oct 30, 2023

Codecov Report

Merging #1378 (4a82701) into openapi (6f89ded) will increase coverage by 0.04%.
The diff coverage is 97.26%.

@@             Coverage Diff             @@
##           openapi    #1378      +/-   ##
===========================================
+ Coverage    90.23%   90.27%   +0.04%     
===========================================
  Files          308      308              
  Lines        10114    10159      +45     
  Branches      1692     1693       +1     
===========================================
+ Hits          9126     9171      +45     
  Misses         651      651              
  Partials       337      337              
Files Coverage Δ
...rc/JsonApiDotNetCore.OpenApi.Client/ApiResponse.cs 100.00% <ø> (ø)
...piDotNetCore.OpenApi/JsonApiOperationIdSelector.cs 84.31% <100.00%> (-0.60%) ⬇️
...rComponents/JsonApiOperationDocumentationFilter.cs 98.17% <100.00%> (+0.26%) ⬆️
...penApi/SwaggerComponents/JsonApiSchemaGenerator.cs 100.00% <100.00%> (ø)
...ggerComponents/ResourceFieldObjectSchemaBuilder.cs 96.80% <100.00%> (+0.02%) ⬆️
...SwaggerComponents/ResourceObjectSchemaGenerator.cs 100.00% <100.00%> (ø)
...onApiDotNetCore.OpenApi/OpenApiSchemaExtensions.cs 81.81% <88.88%> (+31.81%) ⬆️

@bkoelman bkoelman marked this pull request as ready for review October 30, 2023 03:16
@bkoelman bkoelman merged commit b30030a into openapi Oct 30, 2023
16 checks passed
@bkoelman bkoelman deleted the openapi-query-strings branch October 30, 2023 03:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

1 participant