restructure component schemas

packages/plugins/documentation/server/services/helpers/build-api-endpoint-path.js

@@ -122,7 +122,7 @@ const getPaths = ({ routeInfo, uniqueName, contentTypeInfo }) => {
         content: {
           'application/json': {
             schema: {
-              $ref: `#/components/schemas/New${pascalCase(uniqueName)}`,
+              $ref: `#/components/schemas/${pascalCase(uniqueName)}Request`,
             },
           },
         },

packages/plugins/documentation/server/services/helpers/build-component-schema.js

@@ -1,16 +1,13 @@
 'use strict';
 
 const cleanSchemaAttributes = require('./utils/clean-schema-attributes');
-const getSchemaData = require('./utils/get-schema-data');
 const loopContentTypeNames = require('./utils/loop-content-type-names');
 const pascalCase = require('./utils/pascal-case');
 
 /**
- * @decription Gets all open api schema objects for a given content type
+ * @decription Get all open api schema objects for a given content type
  *
  * @param {object} apiInfo
- * @property {string} apiInfo.getter - api | plugin
- * @property {array} apiInfo.ctNames - All contentType names on the api
  * @property {string} apiInfo.uniqueName - Api name | Api name + Content type name
  * @property {object} apiInfo.attributes - Attributes on content type
  * @property {object} apiInfo.routeInfo - The routes for the api
@@ -20,11 +17,10 @@ const pascalCase = require('./utils/pascal-case');
 const getAllSchemasForContentType = ({ routeInfo, attributes, uniqueName }) => {
   // Store response and request schemas in an object
   let schemas = {};
-  // Set flag false since schemas are always objects
-  const isListOfEntities = false;
   // Get all the route methods
   const routeMethods = routeInfo.routes.map(route => route.method);
 
+  // When the route methods contain any post or put requests
   if (routeMethods.includes('POST') || routeMethods.includes('PUT')) {
     const requiredAttributes = Object.entries(attributes)
       .filter(([, attribute]) => attribute.required)
@@ -37,9 +33,10 @@ const getAllSchemasForContentType = ({ routeInfo, attributes, uniqueName }) => {
         ? Object.assign({}, ...requiredAttributes)
         : attributes;
 
+    // Build the request schema
     schemas = {
       ...schemas,
-      [`New${pascalCase(uniqueName)}`]: {
+      [`${pascalCase(uniqueName)}Request`]: {
         type: 'object',
         properties: {
           data: {
@@ -51,9 +48,60 @@ const getAllSchemasForContentType = ({ routeInfo, attributes, uniqueName }) => {
     };
   }
 
+  // Check for routes that need to return a list
+  const hasListOfEntities = routeInfo.routes.filter(
+    route => route.handler.split('.').pop() === 'find'
+  ).length;
+
+  if (hasListOfEntities) {
+    // Build the list response schema
+    schemas = {
+      ...schemas,
+      [`${pascalCase(uniqueName)}ListResponse`]: {
+        properties: {
+          data: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                id: { type: 'string' },
+                attributes: { type: 'object', properties: cleanSchemaAttributes(attributes) },
+              },
+            },
+          },
+          meta: {
+            type: 'object',
+            properties: {
+              pagination: {
+                properties: {
+                  page: { type: 'integer' },
+                  pageSize: { type: 'integer', minimum: 25 },
+                  pageCount: { type: 'integer', maximum: 1 },
+                  total: { type: 'integer' },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+  }
+
+  // Build the response schema
   schemas = {
     ...schemas,
-    [pascalCase(uniqueName)]: getSchemaData(isListOfEntities, cleanSchemaAttributes(attributes)),
+    [`${pascalCase(uniqueName)}Response`]: {
+      properties: {
+        data: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+            attributes: { type: 'object', properties: cleanSchemaAttributes(attributes) },
+          },
+        },
+        meta: { type: 'object' },
+      },
+    },
   };
 
   return schemas;

packages/plugins/documentation/server/services/helpers/utils/get-api-responses.js

@@ -1,55 +1,6 @@
 'use strict';
 
 const pascalCase = require('./pascal-case');
-/**
- *
- * @param {boolean} isSingleEntity - Checks for a single entity
- * @returns {object} The correctly formatted meta object
- */
-const getMeta = isListOfEntities => {
-  if (isListOfEntities) {
-    return {
-      type: 'object',
-      properties: {
-        pagination: {
-          properties: {
-            page: { type: 'integer' },
-            pageSize: { type: 'integer', minimum: 25 },
-            pageCount: { type: 'integer', maximum: 1 },
-            total: { type: 'integer' },
-          },
-        },
-      },
-    };
-  }
-
-  return { type: 'object' };
-};
-
-const getSchemaAsArrayOrObject = (isListOfEntities, name) => {
-  if (isListOfEntities) {
-    return {
-      properties: {
-        data: {
-          type: 'array',
-          items: {
-            $ref: `#/components/schemas/${pascalCase(name)}`,
-          },
-        },
-        meta: getMeta(isListOfEntities),
-      },
-    };
-  }
-
-  return {
-    properties: {
-      data: {
-        $ref: `#/components/schemas/${pascalCase(name)}`,
-      },
-      meta: getMeta(isListOfEntities),
-    },
-  };
-};
 
 /**
  * @description - Builds the Swagger response object for a given api
@@ -60,16 +11,23 @@ const getSchemaAsArrayOrObject = (isListOfEntities, name) => {
  *
  * @returns The Swagger responses
  */
-module.exports = (name, route, isListOfEntities = false) => {
-  let schema;
-  if (route.method === 'DELETE') {
-    schema = {
-      type: 'integer',
-      format: 'int64',
-    };
-  } else {
-    schema = getSchemaAsArrayOrObject(isListOfEntities, name);
-  }
+const getApiResponse = (name, route, isListOfEntities = false) => {
+  const getSchema = () => {
+    if (route.method === 'DELETE') {
+      return {
+        type: 'integer',
+        format: 'int64',
+      };
+    }
+
+    if (isListOfEntities) {
+      return { $ref: `#/components/schemas/${pascalCase(name)}ListResponse` };
+    }
+
+    return { $ref: `#/components/schemas/${pascalCase(name)}Response` };
+  };
+
+  const schema = getSchema();
 
   return {
     responses: {
@@ -134,3 +92,5 @@ module.exports = (name, route, isListOfEntities = false) => {
     },
   };
 };
+
+module.exports = getApiResponse;