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 <59018053+olivermrbl@users.noreply.github.com>
2024-09-18 07:13:51 +00:00
parent a63f6910d0
commit 56ee4d6aad
254 changed files with 6349 additions and 5461 deletions
--- a/www/apps/api-reference/specs/admin/paths/admin_fulfillments_{id}_cancel.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_fulfillments_{id}_cancel.yaml
@@ -45,11 +45,6 @@ post:
    - api_token: []
    - cookie_auth: []
    - jwt_token: []
-  requestBody:
-    content:
-      application/json:
-        schema:
-          $ref: ../components/schemas/AdminCancelFulfillment.yaml
  x-codeSamples:
    - lang: Shell
      label: cURL
--- a/www/apps/api-reference/specs/admin/paths/admin_products_export.yaml
+++ b/www/apps/api-reference/specs/admin/paths/admin_products_export.yaml
@@ -44,11 +44,6 @@ post:
    - api_token: []
    - cookie_auth: []
    - jwt_token: []
-  requestBody:
-    content:
-      application/json:
-        schema:
-          $ref: ../components/schemas/AdminExportProductRequest.yaml
  x-codeSamples:
    - lang: Shell
      label: cURL
--- a/www/apps/api-reference/specs/admin/paths/auth_token_refresh.yaml
+++ b/www/apps/api-reference/specs/admin/paths/auth_token_refresh.yaml
@@ -0,0 +1,38 @@
+post:
+  operationId: PostAdminAuthTokenRefresh
+  summary: Refresh Authentication Token
+  description: >-
+    Refresh the authentication token of a user. This is useful after
+    authenticating a user with a third-party service to ensure the token holds
+    the new user's details, or when you don't want users to re-login every day.
+  externalDocs:
+    url: >-
+      https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#2-third-party-service-authenticate-flow
+    description: Learn about third-party authentication flow.
+  x-authenticated: true
+  x-codeSamples:
+    - lang: Shell
+      label: cURL
+      source:
+        $ref: ../code_samples/Shell/auth_token_refresh/post.sh
+  tags:
+    - Auth
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/AuthResponse.yaml
+    '400':
+      $ref: ../components/responses/400_error.yaml
+    '401':
+      $ref: ../components/responses/unauthorized.yaml
+    '404':
+      $ref: ../components/responses/not_found_error.yaml
+    '409':
+      $ref: ../components/responses/invalid_state_error.yaml
+    '422':
+      $ref: ../components/responses/invalid_request_error.yaml
+    '500':
+      $ref: ../components/responses/500_error.yaml
--- a/www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}.yaml
+++ b/www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}.yaml
@@ -1,9 +1,18 @@
 post:
  operationId: PostActor_typeAuth_provider
  summary: Authenticate User
-  description: >-
-    Authenticate an admin user and receive the JWT token to be used in the
-    header of subsequent requests.
+  description: >
+    Authenticate a user and receive the JWT token to be used in the header of
+    subsequent requests.
+
+
+    When used with a third-party provider, such as Google, the request returns a
+    `location` property. You redirect to the specified URL in your frontend to
+    continue authentication with the third-party service.
+  externalDocs:
+    url: >-
+      https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#types-of-authentication-flows
+    description: Learn about different authentication flows.
  x-authenticated: false
  parameters:
    - name: auth_provider
@@ -13,9 +22,26 @@ post:
      schema:
        type: string
        example: emailpass
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          title: input
+          description: >-
+            The input data necessary for authentication. For example, for
+            email-pass authentication, pass `email` and `password` properties.
  x-codeSamples:
    - lang: Shell
-      label: cURL
+      label: EmailPass Provider
+      source:
+        $ref: ../code_samples/Shell/auth_user_{auth_provider}/post.sh
+    - lang: Shell
+      label: Google Provider
+      source:
+        $ref: ../code_samples/Shell/auth_user_{auth_provider}/post.sh
+    - lang: Shell
+      label: GitHub Provider
      source:
        $ref: ../code_samples/Shell/auth_user_{auth_provider}/post.sh
  tags:
@@ -26,7 +52,9 @@ post:
      content:
        application/json:
          schema:
-            $ref: ../components/schemas/AuthResponse.yaml
+            oneOf:
+              - $ref: ../components/schemas/AuthResponse.yaml
+              - $ref: ../components/schemas/AuthCallbackResponse.yaml
    '400':
      $ref: ../components/responses/400_error.yaml
    '401':
--- a/www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}_callback.yaml
+++ b/www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}_callback.yaml
@@ -1,11 +1,24 @@
 post:
  operationId: PostActor_typeAuth_providerCallback
  summary: Validate Authentication Callback
-  description: >-
-    Third-party authentication providers, such as Google, require an API route
-    to call once authentication with the third-party provider is finished. This
-    API route validates callback for admin users logged-in with third-party
-    providers.
+  description: >
+    This API route is used by your dashboard or frontend application when a
+    third-party provider redirects to it after authentication. 
+
+
+    It validates the authentication with the third-party provider and, if
+    successful, returns an authentication token.
+
+
+    You can decode the JWT token using libraries like
+    [react-jwt](https://www.npmjs.com/package/react-jwt) in the frontend. If the
+    decoded data doesn't  have an `actor_id` property, then you must create a
+    user, typically using the Accept Invite route passing the token in the
+    request's Authorization header.
+  externalDocs:
+    url: >-
+      https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#2-third-party-service-authenticate-flow
+    description: Learn about third-party authentication flow.
  x-authenticated: false
  parameters:
    - name: auth_provider
@@ -17,7 +30,11 @@ post:
        example: google
  x-codeSamples:
    - lang: Shell
-      label: cURL
+      label: Google Provider
+      source:
+        $ref: ../code_samples/Shell/auth_user_{auth_provider}_callback/post.sh
+    - lang: Shell
+      label: GitHub Provider
      source:
        $ref: ../code_samples/Shell/auth_user_{auth_provider}_callback/post.sh
  tags:
--- a/www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}_register.yaml
+++ b/www/apps/api-reference/specs/admin/paths/auth_user_{auth_provider}_register.yaml
@@ -2,9 +2,13 @@ post:
  operationId: PostActor_typeAuth_provider_register
  summary: Retrieve Registration JWT Token
  description: >-
-    A registration JWT token is used in the header of requests that create a
-    user, such as the accept invitation request. This API route retrieves the
-    JWT token of a user that hasn't been registered yet.
+    This API route retrieves a registration JWT token of a user that hasn't been
+    registered yet. The token is used in the header of requests that create a
+    user, such as the Accept Invite API route.
+  externalDocs:
+    url: >-
+      https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#1-basic-authentication-flow
+    description: Learn about the basic authentication flow.
  x-authenticated: false
  parameters:
    - name: auth_provider
@@ -14,6 +18,15 @@ post:
      schema:
        type: string
        example: emailpass
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          title: input
+          description: >-
+            The input data necessary for authentication. For example, for
+            email-pass authentication, pass `email` and `password` properties.
  x-codeSamples:
    - lang: Shell
      label: cURL