docs-util: fixes in schema factory + other improvements (#8874)

- Split schema factory for request / response / common types
- Fix overlapping types "string" and "regexp" to be just one string type
- If `oneOf` or `allOf` OAS schemas have one item, just use that item's type.

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

@@ -546,6 +546,78 @@ class KnowledgeBaseFactory {
         return `Whether the ${singular(options.parentName)} was deleted.`
       },
     },
+    {
+      exact: "$eq",
+      template: `Filter by an exact match.`,
+    },
+    {
+      exact: "$ne",
+      template: `Filter by values not equal to this parameter.`,
+    },
+    {
+      exact: "$in",
+      template: `Filter by values in this array.`,
+    },
+    {
+      exact: "$nin",
+      template: `Filter by values not in this array.`,
+    },
+    {
+      exact: "$not",
+      template: `Filter by values not matching the conditions in this parameter.`,
+    },
+    {
+      exact: "$gt",
+      template: `Filter by values greater than this parameter. Useful for numbers and dates only.`,
+    },
+    {
+      exact: "$gte",
+      template: `Filter by values greater than or equal to this parameter. Useful for numbers and dates only.`,
+    },
+    {
+      exact: "$lt",
+      template: `Filter by values less than this parameter. Useful for numbers and dates only.`,
+    },
+    {
+      exact: "$lte",
+      template: `Filter by values less than or equal to this parameter. Useful for numbers and dates only.`,
+    },
+    {
+      exact: "$like",
+      template: "Apply a `like` filter. Useful for strings only.",
+    },
+    {
+      exact: "$re",
+      template: "Apply a regex filter. Useful for strings only.",
+    },
+    {
+      exact: "$ilike",
+      template:
+        "Apply a case-insensitive `like` filter. Useful for strings only.",
+    },
+    {
+      exact: "$fulltext",
+      template: "Filter to apply on full-text properties.",
+    },
+    {
+      exact: "$overlap",
+      template:
+        "Filter arrays that have overlapping values with this parameter.",
+    },
+    {
+      exact: "$contains",
+      template:
+        "Filter arrays that contain some of the values of this parameter.",
+    },
+    {
+      exact: "$contained",
+      template: "Filter arrays that contain all values of this parameter.",
+    },
+    {
+      exact: "$exists",
+      template:
+        "Filter by whether a value for this parameter exists (not `null`).",
+    },
     {
       pattern: /.*/,
       template(str, options) {

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

@@ -9,24 +9,6 @@ class SchemaFactory {
    * The pre-defined schemas.
    */
   private schemas: Record<string, OpenApiSchema> = {
-    BigNumberInput: {
-      type: "string",
-    },
-    BigNumber: {
-      type: "string",
-    },
-    created_at: {
-      type: "string",
-      format: "date-time",
-    },
-    updated_at: {
-      type: "string",
-      format: "date-time",
-    },
-    deleted_at: {
-      type: "string",
-      format: "date-time",
-    },
     $and: {
       type: "array",
       description:
@@ -43,6 +25,29 @@ class SchemaFactory {
         type: "object",
       },
     },
+    BigNumberInput: {
+      type: "string",
+    },
+    BigNumber: {
+      type: "string",
+    },
+  }
+  /**
+   * Schemas used only for response types.
+   */
+  private schemasForResponse: Record<string, OpenApiSchema> = {
+    created_at: {
+      type: "string",
+      format: "date-time",
+    },
+    updated_at: {
+      type: "string",
+      format: "date-time",
+    },
+    deleted_at: {
+      type: "string",
+      format: "date-time",
+    },
   }
 
   /**
@@ -54,13 +59,21 @@ class SchemaFactory {
    */
   public tryGetSchema(
     name: string,
-    additionalData?: Partial<OpenApiSchema>
+    additionalData?: Partial<OpenApiSchema>,
+    type: "request" | "response" | "all" = "all"
   ): OpenApiSchema | undefined {
-    if (!Object.hasOwn(this.schemas, name)) {
+    const schemasFactory =
+      type === "response"
+        ? this.mergeSchemas(this.schemasForResponse, this.schemas)
+        : this.cloneSchema(this.schemas)
+    const key = Object.hasOwn(schemasFactory, name)
+      ? name
+      : additionalData?.title || ""
+    if (!Object.hasOwn(schemasFactory, key)) {
       return
     }
 
-    let schema = Object.assign({}, this.schemas[name])
+    let schema = Object.assign({}, schemasFactory[key])
 
     if (additionalData) {
       schema = Object.assign(schema, additionalData)
@@ -68,6 +81,19 @@ class SchemaFactory {
 
     return schema
   }
+
+  private mergeSchemas(
+    main: Record<string, OpenApiSchema>,
+    other: Record<string, OpenApiSchema>
+  ): Record<string, OpenApiSchema> {
+    return Object.assign(this.cloneSchema(main), this.cloneSchema(other))
+  }
+
+  private cloneSchema(
+    schema: Record<string, OpenApiSchema>
+  ): Record<string, OpenApiSchema> {
+    return JSON.parse(JSON.stringify(schema))
+  }
 }
 
 export default SchemaFactory