Open APIs

 View Only

Filter Parameter Missing in Swagger OAS

  • 1.  Filter Parameter Missing in Swagger OAS

    TM Forum Member
    Posted Nov 27, 2023 23:19
    Edited by Vance Shipley Nov 28, 2023 01:23

    tldr; the filter parameter should be included in swagger OAS

    All of the specifications ("swagger") in the Open API table, for v4 and v5, define three query parameters: fields, offset and limit.

    These then appear prominently in all tooling which uses the specification.  For example when you import into SwaggerHub you'll see:

    A GET request for productOffering
    This then allows the user to input field values and try it out, right in their browser.
    Many (most?) people use the specifications with code generators.  For instance the above SwaggerHub example offers export options to generate code for client and server.  Choosing to generate a server stub in Javascript provides the following function:

     * List or find ProductOffering objects
     * List or find ProductOffering objects
     * fields String Comma-separated properties to be provided in response (optional)
     * offset Integer Requested index for start of resources to be provided in response (optional)
     * limit Integer Requested number of resources to be provided in response (optional)
     * returns List
    exports.listProductOffering = function(fields,offset,limit) {...}

    The important thing to note here is that only the query parameters defined in the specification are passed in arguments to the function, no other query parameters are available!  This is very limiting as you would be unable to limit the results to a subset of Product Offerings, making it basically useless.

    I propose that the filter parameter, defined in TMF630 Part 6 JSONPath be included in all specifications.  This would then make query parameters available in all of the tooling.

    Vance Shipley