Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
fix: suport complex objects for query params in api explorer
BREAKING CHANGE: This fix has modified the schema described by the decorator 'param.query.object', to support Open-API specification's url-encoded format for json query parameters. Previously, such parameters were described with `exploded: true`, `style: deepObject` which turned out to be problematic, as explained and discussed in, swagger-api/swagger-js#1385 and OAI/OpenAPI-Specification#1706 ```json { "in": "query", "style": "deepObject" "explode": "true", "schema": {} } ``` Exploded encoding worked for json query params if the payload was simple as below, but not for complex objects. ``` http://localhost:3000/todos?filter[limit]=2 ``` To address these issues with exploded queries, this fix modifies the definition of JSON query params from `exploded` and `deep-object` style to the `url-encoded` style described in Open-API spec. The 'style' and 'explode' fields are removed. The 'schema' field is moved under 'content[application/json]' (`url-encoded` style) as below, ```json { "in": "query" "content": { "application/json": { "schema": {} } } } ``` for example, to filter api results with the following condition, ```json { "include": [ { "relation": "todo" } ] } ``` the following url-encoded query parameter is used. ``` http://localhost:3000/todos?filter=%7B%22include%22%3A%5B%7B%22relation%22%3A%22todoList%22%7D%5D%7D ``` To preserve compatibility with existing REST API clients, this change is backward compatible with all previously supported formats for json query parameters. Exploded queries like `?filter[limit]=1` will continue to work, despite the fact that they are described differently in the OpenAPI spec. As a result, existing REST API clients will keep working after an upgrade. LoopBack supported receiving `url-encoded` payload for `exploded`, `deep object` style query params on the server side even before this fix, even though the Open-API spec has very clear demarcations for both these styles. In effect, this fix only clarifies the schema contract as per Open-API spec. The signature of the 'param.query.object' decorator has not changed. There is no code changes required in the LoopBack APIs after upgrading to this fix. No method signatures or data structures are impacted. The impact is only on the open api specifications generated from LoopBack APIs. All consumers of LoopBack APIs may need to regenerate the api specifications, if their API clients or client tools (like swagger-ui or LoopBack's api explorer) necessiate adhering to Open-API's url-encoded query parameter definition to use url-encoding. Otherwise there wouldnt be any significant impact on API consumers.
- Loading branch information