magento2: Magento REST API Schema (Swagger) is not compatible with Search Criteria

Re-opening #7511 per comment https://github.com/magento/magento2/issues/7511#issuecomment-336468740 as this affects 2.0 - 2.2 and hasn’t been resolved.

Preconditions

1. Magento 2 CE or EE (all versions)

Steps to reproduce

1. View Magento-generated Swagger Specification

Expected result

1. Search criteria described in format compatible with Open API / Swagger specification.

Actual result

1. Format not described in a Swagger-compatible manner.
2. Making searchCriteria-related requests using swagger-api/swagger-codegen clients produces an HTTP 400 response from Magento when request sent in described format.

---

The Magento dev docs correctly describe REST API search criteria field groups and filters usage as needing an index per-field group / filter:

searchCriteria[filter_groups][<index>][filters][<index>][field=<field_name>]
searchCriteria[filter_groups][<index>][filters][<index>][value=<search_value>]
searchCriteria[filter_groups][<index>][filters][<index>][condition_type=<operator>]

When viewing the generated Swagger documentation, search criteria is described as follows (without a numerical index):

searchCriteria[filterGroups][][filters][][field]

Sending a request using searchCriteria in the format described by schema.json (without the numerical index) produces an HTTP 400 response. It also does not allow a user to define more than one filterGroup or filter, and breaks swagger-codegen clients.

The searchCriteria implementation doesn’t appear to be compatible with the Open API Specification in the current format.

---

Possible solutions

1. Provide Swagger code-gen templates to workaround the spec
2. Implement a searchCriteria builder endpoint to accept a searchCritera POST body and reply with the query string.
3. Change searchCriteria implementation