docs-util: fixes to base OAS + circular-patch redocly plugin (#7382)

* docs-util: remove MultipleErrors schema from base OAS

* fixes to circular patch plugin

* general fixes

* change nested schemas to references

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

@@ -54,7 +54,7 @@ class OasSchemaHelper {
    * @returns The schema as a reference. If the schema doesn't have the x-schemaName property set,
    * the schema isn't converted and `undefined` is returned.
    */
-  schemaToReference(
+  namedSchemaToReference(
     schema: OpenApiSchema,
     level = 0
   ): OpenAPIV3.ReferenceObject | undefined {
@@ -84,7 +84,7 @@ class OasSchemaHelper {
           !("$ref" in propertySchema.items)
         ) {
           propertySchema.items =
-            this.schemaToReference(propertySchema.items, level + 1) ||
+            this.namedSchemaToReference(propertySchema.items, level + 1) ||
             propertySchema.items
         } else if (
           propertySchema.oneOf ||
@@ -101,13 +101,15 @@ class OasSchemaHelper {
             }
 
             schemaTarget![index] =
-              this.schemaToReference(item, level + 1) || item
+              this.namedSchemaToReference(item, level + 1) || item
           })
         }
 
         schema.properties![property] =
-          this.schemaToReference(propertySchema as OpenApiSchema, level + 1) ||
-          propertySchema
+          this.namedSchemaToReference(
+            propertySchema as OpenApiSchema,
+            level + 1
+          ) || propertySchema
       })
     }
 
@@ -118,6 +120,67 @@ class OasSchemaHelper {
     }
   }
 
+  schemaChildrenToRefs(schema: OpenApiSchema, level = 0): OpenApiSchema {
+    if (level > this.MAX_LEVEL) {
+      return schema
+    }
+
+    const clonedSchema = Object.assign({}, schema)
+
+    if (clonedSchema.allOf) {
+      clonedSchema.allOf = clonedSchema.allOf.map((item) => {
+        if (this.isRefObject(item)) {
+          return item
+        }
+
+        const transformChildItems = this.schemaChildrenToRefs(item, level + 1)
+        return (
+          this.namedSchemaToReference(transformChildItems) ||
+          transformChildItems
+        )
+      })
+    } else if (clonedSchema.oneOf) {
+      clonedSchema.oneOf = clonedSchema.oneOf.map((item) => {
+        if (this.isRefObject(item)) {
+          return item
+        }
+
+        const transformChildItems = this.schemaChildrenToRefs(item, level + 1)
+        return (
+          this.namedSchemaToReference(transformChildItems) ||
+          transformChildItems
+        )
+      })
+    } else if (
+      clonedSchema.type === "array" &&
+      !this.isRefObject(clonedSchema.items)
+    ) {
+      const transformedChildItems = this.schemaChildrenToRefs(
+        clonedSchema.items,
+        level
+      )
+      clonedSchema.items =
+        this.namedSchemaToReference(transformedChildItems) ||
+        transformedChildItems
+    } else if (clonedSchema.properties && !clonedSchema["x-schemaName"]) {
+      Object.entries(clonedSchema.properties).forEach(([key, property]) => {
+        if (this.isRefObject(property)) {
+          return
+        }
+
+        const transformedProperty = this.schemaChildrenToRefs(
+          property,
+          level + 1
+        )
+        schema.properties![key] =
+          this.namedSchemaToReference(transformedProperty) ||
+          transformedProperty
+      })
+    }
+
+    return clonedSchema
+  }
+
   /**
    * Retrieve the expected file name of the schema.
    *
@@ -264,7 +327,11 @@ class OasSchemaHelper {
    */
   tagNameToSchemaName(tagName: string, area: OasArea): string[] {
     const mainSchemaName = wordsToPascal(pluralize.singular(tagName))
-    return [mainSchemaName, `${capitalize(area)}Create${mainSchemaName}`]
+    return [
+      mainSchemaName,
+      `${mainSchemaName}Response`,
+      `${capitalize(area)}Create${mainSchemaName}`,
+    ]
   }
 }
 

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

@@ -15,6 +15,18 @@ class SchemaFactory {
     BigNumber: {
       type: "string",
     },
+    created_at: {
+      type: "string",
+      format: "date-time",
+    },
+    updated_at: {
+      type: "string",
+      format: "date-time",
+    },
+    deleted_at: {
+      type: "string",
+      format: "date-time",
+    },
   }
 
   /**

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

@@ -260,8 +260,8 @@ class OasKindGenerator extends FunctionKindGenerator {
         content: {
           "application/json": {
             schema:
-              this.oasSchemaHelper.schemaToReference(requestSchema) ||
-              requestSchema,
+              this.oasSchemaHelper.namedSchemaToReference(requestSchema) ||
+              this.oasSchemaHelper.schemaChildrenToRefs(requestSchema),
           },
         },
       }
@@ -335,8 +335,8 @@ class OasKindGenerator extends FunctionKindGenerator {
       ;(oas.responses[responseStatus] as OpenAPIV3.ResponseObject).content = {
         "application/json": {
           schema:
-            this.oasSchemaHelper.schemaToReference(responseSchema) ||
-            responseSchema,
+            this.oasSchemaHelper.namedSchemaToReference(responseSchema) ||
+            this.oasSchemaHelper.schemaChildrenToRefs(responseSchema),
         },
       }
     }
@@ -462,7 +462,7 @@ class OasKindGenerator extends FunctionKindGenerator {
       newSchema: requestSchema,
     })
 
-    if (!updatedRequestSchema && existingRequestBodySchema) {
+    if (!updatedRequestSchema) {
       // if there's no request schema, remove it from the OAS
       delete oas.requestBody
     } else {
@@ -470,10 +470,11 @@ class OasKindGenerator extends FunctionKindGenerator {
       oas.requestBody = {
         content: {
           "application/json": {
-            schema: updatedRequestSchema
-              ? this.oasSchemaHelper.schemaToReference(updatedRequestSchema) ||
+            schema:
+              this.oasSchemaHelper.namedSchemaToReference(
                 updatedRequestSchema
-              : updatedRequestSchema,
+              ) ||
+              this.oasSchemaHelper.schemaChildrenToRefs(updatedRequestSchema),
           },
         },
       }
@@ -495,8 +496,10 @@ class OasKindGenerator extends FunctionKindGenerator {
           content: {
             "application/json": {
               schema:
-                this.oasSchemaHelper.schemaToReference(newResponseSchema) ||
-                newResponseSchema,
+                this.oasSchemaHelper.namedSchemaToReference(
+                  newResponseSchema
+                ) ||
+                this.oasSchemaHelper.schemaChildrenToRefs(newResponseSchema),
             },
           },
         },
@@ -532,8 +535,10 @@ class OasKindGenerator extends FunctionKindGenerator {
         content: {
           "application/json": {
             schema: updatedResponseSchema
-              ? this.oasSchemaHelper.schemaToReference(updatedResponseSchema) ||
-                updatedResponseSchema
+              ? this.oasSchemaHelper.namedSchemaToReference(
+                  updatedResponseSchema
+                ) ||
+                this.oasSchemaHelper.schemaChildrenToRefs(updatedResponseSchema)
               : updatedResponseSchema,
           },
         },
@@ -1122,6 +1127,13 @@ class OasKindGenerator extends FunctionKindGenerator {
                   return
                 }
 
+                // check if parameter is already added
+                const isAdded = parameters.some((param) => param.name === key)
+
+                if (isAdded) {
+                  return
+                }
+
                 parameters.push(
                   this.getParameterObject({
                     name: key,
@@ -1134,7 +1146,7 @@ class OasKindGenerator extends FunctionKindGenerator {
               }
             )
           }
-        } else {
+        } else if (methodName !== "delete") {
           requestSchema = parameterSchema
         }
       }
@@ -1273,8 +1285,8 @@ class OasKindGenerator extends FunctionKindGenerator {
           descriptionOptions as SchemaDescriptionOptions
         )
       : title
-      ? this.getSchemaDescription({ typeStr: title, nodeType: itemType })
-      : this.defaultSummary
+        ? this.getSchemaDescription({ typeStr: title, nodeType: itemType })
+        : this.defaultSummary
     const typeAsString =
       zodObjectTypeName || this.checker.typeToString(itemType)
 
@@ -1315,8 +1327,8 @@ class OasKindGenerator extends FunctionKindGenerator {
             itemType.flags === ts.TypeFlags.StringLiteral
               ? "string"
               : itemType.flags === ts.TypeFlags.NumberLiteral
-              ? "number"
-              : "boolean",
+                ? "number"
+                : "boolean",
           title: title || typeAsString,
           description,
           format: this.getSchemaTypeFormat({
@@ -1518,13 +1530,16 @@ class OasKindGenerator extends FunctionKindGenerator {
               : undefined,
           required:
             requiredProperties.length > 0 ? requiredProperties : undefined,
-          properties,
+        }
+
+        if (Object.values(properties).length) {
+          objSchema.properties = properties
         }
 
         if (objSchema["x-schemaName"]) {
           // add object to schemas to be created
           // if necessary
-          this.oasSchemaHelper.schemaToReference(objSchema)
+          this.oasSchemaHelper.namedSchemaToReference(objSchema)
         }
 
         return objSchema
@@ -1826,7 +1841,7 @@ class OasKindGenerator extends FunctionKindGenerator {
     if (oldSchemaObj!.type === "object") {
       if (!oldSchemaObj?.properties && newSchemaObj?.properties) {
         oldSchemaObj!.properties = newSchemaObj.properties
-      } else if (oldSchemaObj?.properties && !newSchemaObj?.properties) {
+      } else if (!newSchemaObj?.properties) {
         delete oldSchemaObj!.properties
       } else {
         // update existing properties