docs-util: fixes for circular references, PAK in examples, namespaces (#9091)

- Fix circular references in generated OAS comments by cloning objects
- Add publishable API key in the header of store cURL examples + change the admin authentication header to use bearer tokens.
- Add plugin to generate namespaces from the `@customNamespace` tag in TSDocs, this was available before but was removed.
- Other fixes related to re-using schemas, overwritten descriptions, and smaller fixes

www/utils/packages/docs-generator/src/classes/helpers/oas-schema.ts

@@ -113,7 +113,9 @@ class OasSchemaHelper {
       })
     }
 
-    this.schemas.set(schema["x-schemaName"], schema)
+    if (this.canAddSchema(schema)) {
+      this.schemas.set(schema["x-schemaName"], schema)
+    }
 
     return {
       $ref: this.constructSchemaReference(schema["x-schemaName"]),
@@ -181,6 +183,36 @@ class OasSchemaHelper {
     return clonedSchema
   }
 
+  isSchemaEmpty(schema: OpenApiSchema): boolean {
+    switch (schema.type) {
+      case "object":
+        return (
+          schema.properties === undefined ||
+          Object.keys(schema.properties).length === 0
+        )
+      case "array":
+        return (
+          !this.isRefObject(schema.items) && this.isSchemaEmpty(schema.items)
+        )
+      default:
+        return false
+    }
+  }
+
+  canAddSchema(schema: OpenApiSchema): boolean {
+    if (!schema["x-schemaName"]) {
+      return false
+    }
+
+    const existingSchema = this.schemas.get(schema["x-schemaName"])
+
+    if (!existingSchema) {
+      return true
+    }
+
+    return this.isSchemaEmpty(existingSchema) && !this.isSchemaEmpty(schema)
+  }
+
   /**
    * Retrieve the expected file name of the schema.
    *
@@ -212,7 +244,7 @@ class OasSchemaHelper {
     // check if it already exists in the schemas map
     if (this.schemas.has(schemaName)) {
       return {
-        schema: this.schemas.get(schemaName)!,
+        schema: JSON.parse(JSON.stringify(this.schemas.get(schemaName)!)),
         schemaPrefix: `@schema ${schemaName}`,
       }
     }
@@ -272,7 +304,7 @@ class OasSchemaHelper {
     return name
       .replace("DTO", "")
       .replace(this.schemaRefPrefix, "")
-      .replace(/(?<!AdminProduct)Type$/, "")
+      .replace(/(?<!(AdminProduct|CreateProduct))Type$/, "")
   }
 
   /**

www/utils/packages/docs-generator/src/classes/helpers/schema-factory.ts

@@ -79,7 +79,7 @@ class SchemaFactory {
       schema = Object.assign(schema, {
         ...additionalData,
         // keep the description
-        description: schema.description || additionalData.description
+        description: schema.description || additionalData.description,
       })
     }