Use "_eq" instead of "=" as query parameter on filters

[iskandersierra]

Describe the bug
When generating the OpenAPI document, a lot of query parameters gets generated for the find queries. Most parameters are of the form _<operator> like _ne and _lt. However the equality operator gets generated as a single equals symbol, like =.

This messes up some client code generators, specially outside javascript world.

The behavior of this when issuing the query is that a url like http://.../restaurant?==test gets generated, and even when it works properly, it seems confusing to me.

Steps to reproduce the behavior

1. Enable documentation plugin
2. Generate the swagger document
3. Open the documentation page in any of the GET / operations
4. Check that there is a parameter with name =

Expected behavior
For consistency and compatibility reasons, the equality operator should be named _eq

Screenshots

System

• Node.js version: 14.5.0
• NPM version: 6.14.5
• Yarn version: 1.22.4
• Strapi version: 3.1.1
• Database: sqlite
• Operating system: Windows 10

** Additional Context **
I know solving this might pose a Breaking Change, and it is not a bug, but a consistency issue.

Thanks for this marvel of a project!

[derrickmehaffy]

@alexandrebodin @soupette I really think we need to just gut all the filters from that plugin as they don't follow the OpenAPI standard, and until we change the query param structure it's pointless to have them. We can keep the _sort, _start, and _limit but all the filters are useless.

[nonameolsson]

Just encountered this error myself. It is actually a showstopper, since we can't rely on the OpenAPI json file to generate the API client.

Any progress on resolving this issue? Or any decision made on how it should be solved. If possible, I could try to help out.

[iskandersierra]

Just encountered this error myself. It is actually a showstopper, since we can't rely on the OpenAPI json file to generate the API client.

Any progress on resolving this issue? Or any decision made on how it should be solved. If possible, I could try to help out.

@nonameolsson I found a solution, overriding function generateVerbParameters at Documentation.js service following the docs here: Plugin extensions

You can copy the entire function to your custom plugin extension and replace line:

return [...params, ...parametersOptions];

by:

return [...params, ...parametersOptions.slice(0, 3)]; // keep _start, _limit and _sort if you like

You also need to import some dependencies included in this function.

You could also use patch-package to patch directly the parametersOptions.json file and remove all unwanted parameters or rename = by eq.

DISCLAIMER: I havn't tested any of this solutions yet, so I do not include a full code. I you do please post the one that worked for you.

[juangallostra]

@nonameolsson @iskandersierra your first suggested approach does indeed work and helps in fixing the issue.

What I've done is:

1. Create a service folder at my-app-name/extensions/documentation (my-app-name/extensions/documentation/service).
2. Create a Documentation.js file inside this service folder.
3. Override the generateVerbParameters function to return only _start, _limit and _sort. The full code of my-app-name/extensions/documentation/service/Documentation.js is then:

'use strict';

/**
 * Override the function generateVerbParameters from the
 * Documentation.js service for the documentation plugin
 *
 * @description: Override generateVerbParameters to avoid issue 
 * https://github.com/strapi/strapi/issues/7219 when generating
 * the OpenAPI document
 */

const _ = require('lodash');
const pathToRegexp = require('path-to-regexp');
const parametersOptions = require('strapi-plugin-documentation/services/utils/parametersOptions.json');
 
module.exports = {
 /**
   * Generate the verb parameters object
   * Refer to https://swagger.io/specification/#pathItemObject
   * @param {Sting} verb
   * @param {String} controllerMethod
   * @param {String} endPoint
   */
  generateVerbParameters: function(verb, controllerMethod, endPoint) {
    const params = pathToRegexp
      .parse(endPoint)
      .filter(token => _.isObject(token))
      .reduce((acc, current) => {
        const param = {
          name: current.name,
          in: 'path',
          description: '',
          deprecated: false,
          required: true,
          schema: { type: 'string' },
        };

        return acc.concat(param);
      }, []);

    if (verb === 'get' && controllerMethod === 'find') {
      // parametersOptions corresponds to this section
      // of the documentation https://strapi.io/documentation/guides/filters.html
      return [...params, ...parametersOptions.slice(0, 3)];
    }

    return params;
    }
}

Now when I run my app only _start, _limit and _sort are available:

[iskandersierra]

Great @juangallostra.

Are you using any client generator from your own documentation? I'm interested to know if the fix is compatible with NSwag to C# client code generation. If not I'll try your solution myself.

Thanks a lot

[derrickmehaffy]

@juangallostra If you would like to submit a PR to gut the filters out of the default doc plugin it would be nice since the current Strapi filtering system won't work with openapi anyway. 😉

[juangallostra]

@derrickmehaffy no problem. I just have two questions before submitting the PR. Do you want me to keep _limit, _sort and _start? And won't this be a breaking change for anybody relying on this filters?

[alexandrebodin]

Hi, there is already a PR that do generate the right filters in the work. please do not work on this for now

[nonameolsson]

@alexandrebodin in which PR?