docs-util: add exceptions for routes with custom auth middleware (#11755)

2025-03-06 13:05:50 +02:00
parent 3616003145
commit 08ce70a368
20 changed files with 228 additions and 58 deletions
@@ -3,7 +3,7 @@
 * operationId: DeleteInvitesId
 * summary: Delete Invite
 * description: Delete an invite.
- * x-authenticated: false
+ * x-authenticated: true
 * parameters:
 *   - name: id
 *     in: path
@@ -56,6 +56,10 @@
 *   "500":
 *     $ref: "#/components/responses/500_error"
 * x-workflow: deleteInvitesWorkflow
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
+ *   - jwt_token: []
 * 
 */

@@ -3,7 +3,7 @@
 * operationId: DeleteUsersId
 * summary: Delete a User
 * description: Delete a user.
- * x-authenticated: false
+ * x-authenticated: true
 * parameters:
 *   - name: id
 *     in: path
@@ -37,6 +37,9 @@
 *   "500":
 *     $ref: "#/components/responses/500_error"
 * x-workflow: removeUserAccountWorkflow
+ * security:
+ *   - cookie_auth: []
+ *   - jwt_token: []
 * 
 */

@@ -3,7 +3,7 @@
 * operationId: GetInvites
 * summary: List Invites
 * description: Retrieve a list of invites. The invites can be filtered by fields such as `id`. The invites can also be sorted or paginated.
- * x-authenticated: false
+ * x-authenticated: true
 * parameters:
 *   - name: fields
 *     in: query
@@ -512,6 +512,10 @@
 *     $ref: "#/components/responses/invalid_request_error"
 *   "500":
 *     $ref: "#/components/responses/500_error"
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
+ *   - jwt_token: []
 * 
 */

@@ -3,7 +3,7 @@
 * operationId: GetInvitesId
 * summary: Get an Invite
 * description: Retrieve an invite by its ID. You can expand the invite's relations or select the fields that should be returned.
- * x-authenticated: false
+ * x-authenticated: true
 * parameters:
 *   - name: id
 *     in: path
@@ -48,6 +48,10 @@
 *     $ref: "#/components/responses/invalid_request_error"
 *   "500":
 *     $ref: "#/components/responses/500_error"
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
+ *   - jwt_token: []
 * 
 */

@@ -3,7 +3,7 @@
 * operationId: GetUsers
 * summary: List Users
 * description: Retrieve a list of users. The users can be filtered by fields such as `id`. The users can also be sorted or paginated.
- * x-authenticated: false
+ * x-authenticated: true
 * parameters:
 *   - name: fields
 *     in: query
@@ -474,6 +474,9 @@
 *     $ref: "#/components/responses/invalid_request_error"
 *   "500":
 *     $ref: "#/components/responses/500_error"
+ * security:
+ *   - cookie_auth: []
+ *   - jwt_token: []
 * 
 */

@@ -3,7 +3,7 @@
 * operationId: GetUsersId
 * summary: Get a User
 * description: Retrieve a user by its ID. You can expand the user's relations or select the fields that should be returned.
- * x-authenticated: false
+ * x-authenticated: true
 * parameters:
 *   - name: id
 *     in: path
@@ -48,6 +48,9 @@
 *     $ref: "#/components/responses/invalid_request_error"
 *   "500":
 *     $ref: "#/components/responses/500_error"
+ * security:
+ *   - cookie_auth: []
+ *   - jwt_token: []
 * 
 */

@@ -3,7 +3,7 @@
 * operationId: GetUsersMe
 * summary: Get Logged-In User
 * description: Retrieve the logged-in user's details.
- * x-authenticated: false
+ * x-authenticated: true
 * parameters:
 *   - name: fields
 *     in: query
@@ -42,6 +42,9 @@
 *     $ref: "#/components/responses/invalid_request_error"
 *   "500":
 *     $ref: "#/components/responses/500_error"
+ * security:
+ *   - cookie_auth: []
+ *   - jwt_token: []
 * 
 */

@@ -3,7 +3,7 @@
 * operationId: PostInvites
 * summary: Create Invite
 * description: Create a invite.
- * x-authenticated: false
+ * x-authenticated: true
 * parameters:
 *   - name: fields
 *     in: query
@@ -65,6 +65,10 @@
 *   "500":
 *     $ref: "#/components/responses/500_error"
 * x-workflow: createInvitesWorkflow
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
+ *   - jwt_token: []
 * 
 */

@@ -3,7 +3,7 @@
 * operationId: PostInvitesIdResend
 * summary: Refresh Invite Token
 * description: Refresh the token of an invite.
- * x-authenticated: false
+ * x-authenticated: true
 * parameters:
 *   - name: id
 *     in: path
@@ -49,6 +49,10 @@
 *   "500":
 *     $ref: "#/components/responses/500_error"
 * x-workflow: refreshInviteTokensWorkflow
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
+ *   - jwt_token: []
 * 
 */

@@ -6,7 +6,7 @@
 *   Accept an invite and create a new user.
 * 
 *   Since the user isn't created yet, the JWT token used in the authorization header is retrieved from the `/auth/user/emailpass/register` API route (or a provider other than `emailpass`). The user can then authenticate using the `/auth/user/emailpass` API route.
- * x-authenticated: false
+ * x-authenticated: true
 * requestBody:
 *   content:
 *     application/json:
@@ -76,6 +76,9 @@
 *   "500":
 *     $ref: "#/components/responses/500_error"
 * x-workflow: acceptInviteWorkflow
+ * security:
+ *   - cookie_auth: []
+ *   - jwt_token: []
 * 
 */

@@ -3,7 +3,7 @@
 * operationId: PostUsersId
 * summary: Update a User
 * description: Update a user's details.
- * x-authenticated: false
+ * x-authenticated: true
 * parameters:
 *   - name: id
 *     in: path
@@ -61,6 +61,9 @@
 *   "500":
 *     $ref: "#/components/responses/500_error"
 * x-workflow: updateUsersWorkflow
+ * security:
+ *   - cookie_auth: []
+ *   - jwt_token: []
 * 
 */

@@ -52,6 +52,8 @@ type AuthRequests = {
  exact?: string
  startsWith?: string
  requiresAuthentication: boolean
+  allowedAuthTypes?: string[]
+  httpMethods?: string[]
 }

 /**
@@ -99,6 +101,21 @@ class OasKindGenerator extends FunctionKindGenerator {
      exact: "store/orders/[id]/transfer/cancel",
      requiresAuthentication: true,
    },
+    {
+      exact: "admin/invites/accept",
+      httpMethods: ["post"],
+      requiresAuthentication: true,
+      allowedAuthTypes: ["cookie_auth", "jwt_token"],
+    },
+    {
+      startsWith: "admin/invites",
+      requiresAuthentication: true,
+    },
+    {
+      startsWith: "admin/users",
+      requiresAuthentication: true,
+      allowedAuthTypes: ["cookie_auth", "jwt_token"],
+    },
  ]
  readonly RESPONSE_TYPE_NAMES = ["MedusaResponse"]
  readonly FIELD_QUERY_PARAMS = ["fields", "expand"]
@@ -275,8 +292,12 @@ class OasKindGenerator extends FunctionKindGenerator {
    const { oasPath, normalized: normalizedOasPath } = this.getOasPath(node)
    const splitOasPath = oasPath.split("/")
    const oasPrefix = this.getOasPrefix(methodName, normalizedOasPath)
-    const { isAdminAuthenticated, isStoreAuthenticated, isAuthenticated } =
-      this.getAuthenticationDetails(node, oasPath)
+    const {
+      isAdminAuthenticated,
+      isStoreAuthenticated,
+      isAuthenticated,
+      allowedAuthTypes,
+    } = this.getAuthenticationDetails(node, oasPath, methodName)
    const tagName = this.getTagName(splitOasPath)
    const { summary, description } =
      this.knowledgeBaseFactory.tryToGetOasMethodSummaryAndDescription({
@@ -370,7 +391,11 @@ class OasKindGenerator extends FunctionKindGenerator {
    }

    // add security details if applicable
-    oas.security = this.getSecurity({ isAdminAuthenticated, isAuthenticated })
+    oas.security = this.getSecurity({
+      isAdminAuthenticated,
+      isAuthenticated,
+      auth_types: allowedAuthTypes,
+    })

    if (tagName) {
      oas.tags = [tagName]
@@ -484,11 +509,19 @@ class OasKindGenerator extends FunctionKindGenerator {
    }

    // check if authentication details (including security) should be updated
-    const { isAdminAuthenticated, isStoreAuthenticated, isAuthenticated } =
-      this.getAuthenticationDetails(node, oasPath)
+    const {
+      isAdminAuthenticated,
+      isStoreAuthenticated,
+      isAuthenticated,
+      allowedAuthTypes,
+    } = this.getAuthenticationDetails(node, oasPath, methodName)

    oas["x-authenticated"] = isAuthenticated
-    oas.security = this.getSecurity({ isAdminAuthenticated, isAuthenticated })
+    oas.security = this.getSecurity({
+      isAdminAuthenticated,
+      isAuthenticated,
+      auth_types: allowedAuthTypes,
+    })

    let parametersUpdated = false

@@ -815,7 +848,8 @@ class OasKindGenerator extends FunctionKindGenerator {
   */
  getAuthenticationDetails(
    node: FunctionNode,
-    oasPath: string
+    oasPath: string,
+    httpMethod: string
  ): {
    /**
     * Whether the OAS operation requires admin authentication.
@@ -829,34 +863,42 @@ class OasKindGenerator extends FunctionKindGenerator {
     * Whether the OAS operation requires authentication in genral.
     */
    isAuthenticated: boolean
+    /**
+     * Override the default security requirements.
+     */
+    allowedAuthTypes?: string[]
  } {
    const isAuthenticationDisabled = node
      .getSourceFile()
      .statements.some((statement) =>
        statement.getText().includes("AUTHENTICATE = false")
      )
-    const hasAuthenticationOverride =
-      this.AUTH_REQUESTS.find((authRequest) => {
-        return (
-          authRequest.exact === oasPath ||
-          (authRequest.startsWith && oasPath.startsWith(authRequest.startsWith))
-        )
-      })?.requiresAuthentication === true
+    const hasAuthenticationOverride = this.AUTH_REQUESTS.find((authRequest) => {
+      const pathMatch =
+        authRequest.exact === oasPath ||
+        (authRequest.startsWith && oasPath.startsWith(authRequest.startsWith))
+      const httpMethodMatch =
+        !authRequest.httpMethods || authRequest.httpMethods.includes(httpMethod)
+      return pathMatch && httpMethodMatch
+    })
+    const isAuthRequired =
+      hasAuthenticationOverride?.requiresAuthentication === true
    const isAdminAuthenticated =
-      (!isAuthenticationDisabled || hasAuthenticationOverride) &&
+      (!isAuthenticationDisabled || isAuthRequired) &&
      oasPath.startsWith("admin")
-    const isStoreAuthenticated = hasAuthenticationOverride
+    const isStoreAuthenticated = isAuthRequired
      ? oasPath.startsWith("store")
      : !isAuthenticationDisabled &&
-        hasAuthenticationOverride &&
+        isAuthRequired &&
        oasPath.startsWith("store")
    const isAuthenticated =
-      isAdminAuthenticated || isStoreAuthenticated || hasAuthenticationOverride
+      isAdminAuthenticated || isStoreAuthenticated || isAuthRequired

    return {
      isAdminAuthenticated,
      isStoreAuthenticated,
      isAuthenticated,
+      allowedAuthTypes: hasAuthenticationOverride?.allowedAuthTypes,
    }
  }

@@ -903,6 +945,7 @@ class OasKindGenerator extends FunctionKindGenerator {
  getSecurity({
    isAdminAuthenticated,
    isAuthenticated,
+    auth_types,
  }: {
    /**
     * Whether the operation requires admin authentication.
@@ -912,22 +955,35 @@ class OasKindGenerator extends FunctionKindGenerator {
     * Whether the operation requires general authentication.
     */
    isAuthenticated: boolean
+    /**
+     * Override the default security requirements.
+     */
+    auth_types?: string[]
  }): OpenAPIV3.SecurityRequirementObject[] | undefined {
    const security: OpenAPIV3.SecurityRequirementObject[] = []
-    if (isAdminAuthenticated) {
+    const allowed_auth_types =
+      auth_types ||
+      [
+        "cookie_auth",
+        "jwt_token",
+        isAdminAuthenticated ? "api_token" : undefined,
+      ].filter(Boolean)
+    if (isAdminAuthenticated && allowed_auth_types.includes("api_token")) {
      security.push({
        api_token: [],
      })
    }
    if (isAuthenticated) {
-      security.push(
-        {
+      if (allowed_auth_types.includes("cookie_auth")) {
+        security.push({
          cookie_auth: [],
-        },
-        {
+        })
+      }
+      if (allowed_auth_types.includes("jwt_token")) {
+        security.push({
          jwt_token: [],
-        }
-      )
+        })
+      }
    }

    return security.length ? security : undefined