📝 [#472] update OAS with 'data_attr' filter

src/objects/api/v2/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: Objects API
-  version: 2.4.3 (v2)
+  version: 2.4.3
   description: |
     An API to manage Objects.
 
@@ -89,12 +89,49 @@ paths:
           data. According to the GeoJSON spec, WGS84 is the default (EPSG: 4326 is
           the same as WGS84).'
       - in: query
-        name: data_attrs
+        name: data_attr
         schema:
           type: string
         description: |
           Only include objects that have attributes with certain values.
+
+          A valid parameter value has the form `key__operator__value`.
+          `key` is the attribute name, `operator` is the comparison operator to be used and `value` is the attribute value.
+          Note: Values can be string, numeric, or dates (ISO format; YYYY-MM-DD).
+
+          Valid operator values are:
+          * `exact` - equal to
+          * `gt` - greater than
+          * `gte` - greater than or equal to
+          * `lt` - lower than
+          * `lte` - lower than or equal to
+          * `icontains` - case-insensitive partial match
+          * `in` - in a list of values separated by `|`
+
+          `value` may not contain double underscore or comma characters.
+          `key` may not contain comma characters and includes double underscore only if it indicates nested attributes.
+
+
+
+          Example: in order to display only objects with `height` equal to 100, query `data_attr=height__exact__100`
+          should be used. If `height` is nested inside `dimensions` attribute, query should look like
+          `data_attr=dimensions__height__exact__100`
+
+          This filter is very similar to the old `data_attrs` filter, but it has two differences:
+
+          * `value` may contain commas
+          * only one filtering expression is allowed
+
+          If you want to use several filtering expressions, just use this `data_attr` several times in the query string.
+          Example: `data_attr=height__exact__100&data_attr=naam__icontains__boom`
+      - in: query
+        name: data_attrs
+        schema:
+          type: string
+        description: |
+          **DEPRECATED**: Only include objects that have attributes with certain values.
           Data filtering expressions are comma-separated and are structured as follows:
+
           A valid parameter value has the form `key__operator__value`.
           `key` is the attribute name, `operator` is the comparison operator to be used and `value` is the attribute value.
           Note: Values can be string, numeric, or dates (ISO format; YYYY-MM-DD).
@@ -111,9 +148,14 @@ paths:
           `value` may not contain double underscore or comma characters.
           `key` may not contain comma characters and includes double underscore only if it indicates nested attributes.
 
+
+
           Example: in order to display only objects with `height` equal to 100, query `data_attrs=height__exact__100`
           should be used. If `height` is nested inside `dimensions` attribute, query should look like
           `data_attrs=dimensions__height__exact__100`
+
+          `value` may not contain comma, since commas are used as separator between filtering expressions.
+          If you want to use commas in `value` you can use `data_attr` query parameter.
       - in: query
         name: data_icontains
         schema:
@@ -620,8 +662,9 @@ paths:
                   data_attrs:
                     type: string
                     description: |
-                      Only include objects that have attributes with certain values.
+                      **DEPRECATED**: Only include objects that have attributes with certain values.
                       Data filtering expressions are comma-separated and are structured as follows:
+
                       A valid parameter value has the form `key__operator__value`.
                       `key` is the attribute name, `operator` is the comparison operator to be used and `value` is the attribute value.
                       Note: Values can be string, numeric, or dates (ISO format; YYYY-MM-DD).
@@ -638,9 +681,48 @@ paths:
                       `value` may not contain double underscore or comma characters.
                       `key` may not contain comma characters and includes double underscore only if it indicates nested attributes.
 
+
+
                       Example: in order to display only objects with `height` equal to 100, query `data_attrs=height__exact__100`
                       should be used. If `height` is nested inside `dimensions` attribute, query should look like
                       `data_attrs=dimensions__height__exact__100`
+
+                      `value` may not contain comma, since commas are used as separator between filtering expressions.
+                      If you want to use commas in `value` you can use `data_attr` query parameter.
+                  data_attr:
+                    type: string
+                    description: |
+                      Only include objects that have attributes with certain values.
+
+                      A valid parameter value has the form `key__operator__value`.
+                      `key` is the attribute name, `operator` is the comparison operator to be used and `value` is the attribute value.
+                      Note: Values can be string, numeric, or dates (ISO format; YYYY-MM-DD).
+
+                      Valid operator values are:
+                      * `exact` - equal to
+                      * `gt` - greater than
+                      * `gte` - greater than or equal to
+                      * `lt` - lower than
+                      * `lte` - lower than or equal to
+                      * `icontains` - case-insensitive partial match
+                      * `in` - in a list of values separated by `|`
+
+                      `value` may not contain double underscore or comma characters.
+                      `key` may not contain comma characters and includes double underscore only if it indicates nested attributes.
+
+
+
+                      Example: in order to display only objects with `height` equal to 100, query `data_attr=height__exact__100`
+                      should be used. If `height` is nested inside `dimensions` attribute, query should look like
+                      `data_attr=dimensions__height__exact__100`
+
+                      This filter is very similar to the old `data_attrs` filter, but it has two differences:
+
+                      * `value` may contain commas
+                      * only one filtering expression is allowed
+
+                      If you want to use several filtering expressions, just use this `data_attr` several times in the query string.
+                      Example: `data_attr=height__exact__100&data_attr=naam__icontains__boom`
                   date:
                     type: string
                     format: date