docs-util: add support for RequestWithContext in route-handler detection (#8141)

* docs-util: update OAS docblock-generator to support RequestWithContext

* support alias type arguments in case there are no type arguments

www/utils/packages/docblock-generator/package.json

@@ -2,7 +2,7 @@
   "name": "docblock-generator",
   "license": "MIT",
   "scripts": {
-    "dev": "ts-node src/index.ts",
+    "dev": "node --loader ts-node/esm src/index.ts",
     "start": "node dist/index.js",
     "build": "tsc",
     "watch": "tsc --watch",

www/utils/packages/docblock-generator/src/classes/kinds/oas.ts

@@ -49,6 +49,12 @@ class OasKindGenerator extends FunctionKindGenerator {
   public name = "oas"
   protected allowedKinds: SyntaxKind[] = [ts.SyntaxKind.FunctionDeclaration]
   private MAX_LEVEL = 4
+  readonly REQUEST_TYPE_NAMES = [
+    "MedusaRequest",
+    "RequestWithContext",
+    "AuthenticatedMedusaRequest",
+  ]
+  readonly RESPONSE_TYPE_NAMES = ["MedusaResponse"]
 
   /**
    * This map collects tags of all the generated OAS, then, once the generation process finishes,
@@ -82,7 +88,7 @@ class OasKindGenerator extends FunctionKindGenerator {
 
   /**
    * Check whether the generator can be used for the specified node. The node must be a function that has
-   * two parameters of types `MedusaRequest` and `MedusaResponse` respectively.
+   * two parameters of types in {@link REQUEST_TYPE_NAMES} and {@link RESPONSE_TYPE_NAMES}
    *
    * @param node - The node to check.
    * @returns Whether the generator can be used for the specified node.
@@ -100,25 +106,18 @@ class OasKindGenerator extends FunctionKindGenerator {
       ? node
       : this.extractFunctionNode(node as VariableNode)
 
-    if (!functionNode) {
+    if (!functionNode || functionNode.parameters.length !== 2) {
       return false
     }
 
-    // function must have 2 parameters, first parameter of type `MedusaRequest`
+    const hasCorrectRequestType = this.REQUEST_TYPE_NAMES.some(
-    // and the second of type `MedusaResponse`
+      (name) => functionNode.parameters[0].type?.getText().startsWith(name)
-    return (
-      (functionNode.parameters.length === 2 &&
-        (functionNode.parameters[0].type
-          ?.getText()
-          .startsWith("MedusaRequest") ||
-          functionNode.parameters[0].type
-            ?.getText()
-            .startsWith("AuthenticatedMedusaRequest")) &&
-        functionNode.parameters[1].type
-          ?.getText()
-          .startsWith("MedusaResponse")) ||
-      false
     )
+    const hasCorrectResponseType = this.RESPONSE_TYPE_NAMES.some(
+      (name) => functionNode.parameters[1].type?.getText().startsWith(name)
+    )
+
+    return hasCorrectRequestType && hasCorrectResponseType
   }
 
   /**
@@ -976,9 +975,10 @@ class OasKindGenerator extends FunctionKindGenerator {
         })
       }
 
-      const requestTypeArguments = this.checker.getTypeArguments(requestType)
+      const requestTypeArguments =
+        requestType.typeArguments || requestType.aliasTypeArguments
 
-      if (requestTypeArguments.length === 1) {
+      if (requestTypeArguments?.length === 1) {
         const zodObjectTypeName = getCorrectZodTypeName({
           typeReferenceNode: node.parameters[0].type,
           itemType: requestTypeArguments[0],