docs: add /api/v1/insights endpoint to documentation

openfoodfacts · Oct 29, 2024 · f5b1de4 · f5b1de4
1 parent d8534fe
commit f5b1de4
Showing 1 changed file with 89 additions and 2 deletions.
diff --git a/doc/references/api.yml b/doc/references/api.yml
@@ -261,7 +261,8 @@ paths:
     get:
       tags:
         - Insights
-      summary: Get a random insight
+      deprecated: true
+      summary: Get a random insight, use GET /insights?order_by=random instead
       parameters:
         - $ref: "#/components/parameters/insight_type"
         - $ref: "#/components/parameters/countries"
@@ -285,14 +286,55 @@ paths:
     get:
       tags:
         - Insights
-      summary: Get all insights for a specific product
+      deprecated: true
+      summary: Get all insights for a specific product, use GET /insights?barcode={barcode} instead
       parameters:
         - $ref: "#/components/parameters/barcode_path"
         - $ref: "#/components/parameters/server_type"
       responses:
         "200":
           description: ""
           content: {}
+  /insights:
+    get:
+      tags:
+        - Insights
+      summary: List insights
+      parameters:
+        - $ref: "#/components/parameters/insight_types"
+        - $ref: "#/components/parameters/barcode_optional"
+        - $ref: "#/components/parameters/insight_filter_annotated"
+        - $ref: "#/components/parameters/insight_filter_annotation"
+        - $ref: "#/components/parameters/value_tag"
+        - $ref: "#/components/parameters/brands"
+        - $ref: "#/components/parameters/countries"
+        - $ref: "#/components/parameters/server_type"
+        - $ref: "#/components/parameters/predictor"
+        - $ref: "#/components/parameters/insight_order_by"
+        - $ref: "#/components/parameters/count"
+        - $ref: "#/components/parameters/page"
+      responses:
+        "200":
+          description: ""
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  insights:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/InsightSearchResult"
+                  status:
+                    type: string
+                    enum:
+                      - "no_insights"
+                      - "found"
+                    example: "found"
+                  count:
+                    type: integer
+                    description: The total number of results with the provided filters
+                    example: 10
   /insights/detail/{id}:
     get:
       tags:
@@ -1355,6 +1397,7 @@ components:
       description: Comma-separated list, filter by brands
       schema:
         type: string
+        example: "carrefour,ferrero"
     value_tag:
       name: value_tag
       in: query
@@ -1393,6 +1436,20 @@ components:
       schema:
         type: string
         example: universal-logo-detector
+    insight_order_by:
+      name: order_by
+      in: query
+      description: |
+        How to order by insight results.
+        By default, results are not ordered. Possible values are:
+          - `random`: insights are ordered randomly
+          - `popularity`: insights are returned by decreasing popularity, using the number of scans as proxy
+      schema:
+        type: string
+        enum:
+          - random
+          - popularity
+        example: popularity
     ann_search_count:
       name: count
       in: query
@@ -1418,6 +1475,36 @@ components:
       schema:
         type: integer
         example: 5410041040807
+    barcode_optional:
+      name: barcode
+      in: query
+      required: false
+      description: Filter by barcode value
+      schema:
+        type: integer
+        example: 5410041040807
+    insight_filter_annotated:
+      name: annotated
+      in: query
+      required: false
+      description: Filter by annotation status of the insight.
+        A true value (`1`, `true`) means we only return annotated insights, 
+        a false value (`0`, `false`) only non-annotated insights.
+        If the parameter is not provided, both annotated and non-annotated
+        insights are returned.
+      schema:
+        type: boolean
+        example: true
+    insight_filter_annotation:
+      name: annotation
+      in: query
+      required: false
+      description: Filter by annotation value of the insight.
+        If not provided, all insights are returned.
+        This works in conjunction with the `annotated` parameter. 
+      schema:
+        type: integer
+        example: 1
     job_type:
       name: job_type
       in: query