chore(docs): Generated API Reference (#4706)

Co-authored-by: olivermrbl <olivermrbl@users.noreply.github.com>
Co-authored-by: Shahed Nasser <shahednasser@gmail.com>

docs/api/admin/paths/admin_discounts.yaml

@@ -2,16 +2,18 @@ get:
   operationId: GetDiscounts
   summary: List Discounts
   x-authenticated: true
-  description: Retrieves a list of Discounts
+  description: >-
+    Retrieve a list of Discounts. The discounts can be filtered by fields such
+    as `rule` or `is_dynamic`. The discounts can also be paginated.
   parameters:
     - in: query
       name: q
-      description: Search query applied on the code field.
+      description: term to search discounts' code field.
       schema:
         type: string
     - in: query
       name: rule
-      description: Discount Rules filters to apply on the search
+      description: Filter discounts by rule fields.
       schema:
         type: object
         properties:
@@ -21,43 +23,40 @@ get:
               - fixed
               - percentage
               - free_shipping
-            description: >-
-              The type of the Discount, can be `fixed` for discounts that reduce
-              the price by a fixed amount, `percentage` for percentage
-              reductions or `free_shipping` for shipping vouchers.
+            description: Filter discounts by type.
           allocation:
             type: string
             enum:
               - total
               - item
-            description: >-
-              The value that the discount represents; this will depend on the
-              type of the discount
+            description: Filter discounts by allocation type.
     - in: query
       name: is_dynamic
-      description: Return only dynamic discounts.
+      description: Filter discounts by whether they're dynamic or not.
       schema:
         type: boolean
     - in: query
       name: is_disabled
-      description: Return only disabled discounts.
+      description: Filter discounts by whether they're disabled or not.
       schema:
         type: boolean
     - in: query
       name: limit
-      description: The number of items in the response
+      description: The number of discounts to return
       schema:
         type: number
         default: '20'
     - in: query
       name: offset
-      description: The offset of items in response
+      description: The number of discounts to skip when retrieving the discounts.
       schema:
         type: number
         default: '0'
     - in: query
       name: expand
-      description: Comma separated list of relations to include in the results.
+      description: >-
+        Comma-separated relations that should be expanded in each returned
+        discount.
       schema:
         type: string
   x-codegen:
@@ -98,20 +97,24 @@ get:
       $ref: ../components/responses/500_error.yaml
 post:
   operationId: PostDiscounts
-  summary: Creates a Discount
+  summary: Create a Discount
   x-authenticated: true
   description: >-
-    Creates a Discount with a given set of rules that define how the Discount
-    behaves.
+    Create a Discount with a given set of rules that defines how the Discount is
+    applied.
   parameters:
     - in: query
       name: expand
-      description: (Comma separated) Which fields should be expanded in the results.
+      description: >-
+        Comma-separated relations that should be expanded in the returned
+        discount.
       schema:
         type: string
     - in: query
       name: fields
-      description: (Comma separated) Which fields should be retrieved in the results.
+      description: >-
+        Comma-separated fields that should be retrieved in the returned
+        discount.
       schema:
         type: string
   requestBody: