chore(docs): Updated API Reference (v2) (#9148)

Automated changes by [create-pull-request](https://github.com/peter-evans/create-pull-request) GitHub action

Co-authored-by: Oli Juhl <[email protected]>

www/apps/api-reference/specs/admin/code_samples/Shell/auth_token_refresh/post.sh

@@ -0,0 +1,2 @@
+curl -X POST '{backend_url}/auth/token/refresh' \
+-H 'Authorization: Bearer {token}'

www/apps/api-reference/specs/admin/code_samples/Shell/auth_user_{auth_provider}/post.sh

@@ -1 +1 @@
-curl -X POST '{backend_url}/auth/user/{auth_provider}'
+curl -X POST '{backend_url}/auth/user/github'

www/apps/api-reference/specs/admin/code_samples/Shell/auth_user_{auth_provider}_callback/post.sh

@@ -1 +1 @@
-curl -X POST '{backend_url}/auth/user/{auth_provider}/callback'
+curl -X POST '{backend_url}/auth/user/github/callback?code=123'

www/apps/api-reference/specs/admin/code_samples/Shell/auth_user_{auth_provider}_register/post.sh

@@ -1 +1,6 @@
-curl -X POST '{backend_url}/auth/user/{auth_provider}/register'
+curl -X POST '{backend_url}/auth/user/emailpass/register' \
+-H 'Content-Type: application/json' \
+--data-raw '{
+  "email": "[email protected]",
+  "password": "supersecret"
+}'

www/apps/api-reference/specs/admin/components/schemas/AdminApiKey.yaml

@@ -1,5 +1,5 @@
 type: object
-description: The api key's details.
+description: The API key's details.
 x-schemaName: AdminApiKey
 required:
   - id
@@ -24,37 +24,44 @@ properties:
   redacted:
     type: string
     title: redacted
-    description: The api key's redacted.
+    description: >-
+      The redacted form of the API key's token. This is useful when showing
+      portion of the token.
+    example: sk_...123
   title:
     type: string
     title: title
     description: The api key's title.
   type:
     type: string
-    description: The api key's type.
+    description: >-
+      The api key's type. `secret` is used for a user's API key, whereas
+      `publishable` is used for Publishable API keys.
     enum:
       - secret
       - publishable
   last_used_at:
     type: string
     title: last_used_at
-    description: The api key's last used at.
+    description: The date and time the API key was last used.
     format: date-time
   created_by:
     type: string
     title: created_by
-    description: The api key's created by.
+    description: The ID of the user that created the API key, if available.
   created_at:
     type: string
     format: date-time
     title: created_at
-    description: The api key's created at.
+    description: The date and time the API key was created.
   revoked_by:
     type: string
     title: revoked_by
-    description: The api key's revoked by.
+    description: The ID of the user that revoked the API key, if available.
   revoked_at:
     type: string
     title: revoked_at
-    description: The api key's revoked at.
+    description: >-
+      The date and time the API key was revoked. The API key is considered
+      revoked when this property is set.
     format: date-time

www/apps/api-reference/specs/admin/components/schemas/AdminApiKeyResponse.yaml

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The API key's details.
 x-schemaName: AdminApiKeyResponse
 required:
   - api_key

www/apps/api-reference/specs/admin/components/schemas/AdminBatchProductRequest.yaml

@@ -1,21 +1,21 @@
 type: object
-description: SUMMARY
+description: The products to create, update, or delete.
 x-schemaName: AdminBatchProductRequest
 properties:
   create:
     type: array
-    description: The product's create.
+    description: The products to create.
     items:
       $ref: ./AdminCreateProduct.yaml
   update:
     type: array
-    description: The product's update.
+    description: The products to update.
     items:
       $ref: ./AdminUpdateProduct.yaml
   delete:
     type: array
-    description: The product's delete.
+    description: The products to delete.
     items:
       type: string
       title: delete
-      description: The delete's details.
+      description: A product's ID.

www/apps/api-reference/specs/admin/components/schemas/AdminBatchProductResponse.yaml

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of the products created, updated, or deleted.
 x-schemaName: AdminBatchProductResponse
 required:
   - created
@@ -8,34 +8,35 @@ required:
 properties:
   created:
     type: array
-    description: The product's created.
+    description: The created products
     items:
       $ref: ./AdminProduct.yaml
   updated:
     type: array
-    description: The product's updated.
+    description: The updated products.
     items:
       $ref: ./AdminProduct.yaml
   deleted:
     type: object
-    description: SUMMARY
+    description: The deleted products' details.
     required:
       - ids
       - object
       - deleted
     properties:
       ids:
         type: array
-        description: The deleted's ids.
+        description: The IDs of deleted products.
         items:
           type: string
           title: ids
-          description: The id's ids.
+          description: The ID of a deleted product.
       object:
         type: string
         title: object
-        description: SUMMARY
+        description: The name of the deleted objects.
+        default: product
       deleted:
         type: boolean
         title: deleted
-        description: SUMMARY
+        description: Whether the products were deleted.

www/apps/api-reference/specs/admin/components/schemas/AdminBatchProductVariantRequest.yaml

@@ -1,21 +1,21 @@
 type: object
-description: SUMMARY
+description: The product variants to create, update, or delete.
 x-schemaName: AdminBatchProductVariantRequest
 properties:
   create:
     type: array
-    description: The product's create.
+    description: The product variants to create.
     items:
       $ref: ./AdminCreateProductVariant.yaml
   update:
     type: array
-    description: The product's update.
+    description: The product variants to update.
     items:
       $ref: ./AdminUpdateProductVariant.yaml
   delete:
     type: array
-    description: The product's delete.
+    description: The product variants to delete.
     items:
       type: string
       title: delete
-      description: The delete's details.
+      description: A product variant's ID.

www/apps/api-reference/specs/admin/components/schemas/AdminBatchProductVariantResponse.yaml

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The details of the product variants created, updated, or deleted.
 x-schemaName: AdminBatchProductVariantResponse
 required:
   - created
@@ -8,34 +8,35 @@ required:
 properties:
   created:
     type: array
-    description: The product's created.
+    description: The created product variants.
     items:
       $ref: ./AdminProductVariant.yaml
   updated:
     type: array
-    description: The product's updated.
+    description: The updated product variants.
     items:
       $ref: ./AdminProductVariant.yaml
   deleted:
     type: object
-    description: SUMMARY
+    description: The details of the deleted product variants.
     required:
       - ids
       - object
       - deleted
     properties:
       ids:
         type: array
-        description: The deleted's ids.
+        description: The IDs of the deleted product variants.
         items:
           type: string
           title: ids
-          description: The id's ids.
+          description: The ID of a deleted variant.
       object:
         type: string
         title: object
-        description: SUMMARY
+        description: The name of the deleted objects.
+        default: variant
       deleted:
         type: boolean
         title: deleted
-        description: SUMMARY
+        description: Whether the product variants were deleted.

www/apps/api-reference/specs/admin/components/schemas/AdminCampaign.yaml

@@ -30,15 +30,15 @@ properties:
   campaign_identifier:
     type: string
     title: campaign_identifier
-    description: The campaign's campaign identifier.
+    description: The campaign's identifier.
   starts_at:
     type: string
     title: starts_at
-    description: The campaign's starts at.
+    description: The date and time that the campaign starts.
   ends_at:
     type: string
     title: ends_at
-    description: The campaign's ends at.
+    description: The date and time that the campaign ends.
   budget:
     type: object
     description: The campaign's budget.
@@ -55,7 +55,11 @@ properties:
         description: The budget's ID.
       type:
         type: string
-        description: The budget's type.
+        description: >
+          The budget's type. `spend` means the limit is set on the total amount
+          discounted by the campaign's promotions; `usage` means the limit is
+          set on the total number of times the campaign's promotions can be
+          used.
         enum:
           - spend
           - usage
@@ -70,4 +74,8 @@ properties:
       used:
         type: number
         title: used
-        description: The budget's used.
+        description: >
+          How much of the budget has been used. If the limit is `spend`, this
+          property holds the total amount discounted so far. If the limit is
+          `usage`, it holds the number of times the campaign's promotions have
+          been used so far.

www/apps/api-reference/specs/admin/components/schemas/AdminCampaignResponse.yaml

@@ -1,5 +1,5 @@
 type: object
-description: SUMMARY
+description: The campaign's details.
 x-schemaName: AdminCampaignResponse
 required:
   - campaign