@strapi/plugin-documentation 0.0.0-02af04644a1b236c1add59b27e2da1cfd7843fc5

package/server/services/helpers/build-component-schema.js

@@ -0,0 +1,216 @@
+'use strict';
+
+const _ = require('lodash');
+
+const cleanSchemaAttributes = require('./utils/clean-schema-attributes');
+const loopContentTypeNames = require('./utils/loop-content-type-names');
+const pascalCase = require('./utils/pascal-case');
+const { hasFindMethod, isLocalizedPath } = require('./utils/routes');
+
+/**
+ * @decription Get all open api schema objects for a given content type
+ *
+ * @param {object} apiInfo
+ * @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
+ *
+ * @returns {object} Open API schemas
+ */
+const getAllSchemasForContentType = ({ routeInfo, attributes, uniqueName }) => {
+  // Store response and request schemas in an object
+  let schemas = {};
+  let componentSchemas = {};
+  // adds a ComponentSchema to the Schemas so it can be used as Ref
+  const addComponentSchema = (schemaName, schema) => {
+    if (!Object.keys(schema) || !Object.keys(schema.properties)) {
+      return false;
+    }
+    componentSchemas = {
+      ...componentSchemas,
+      [schemaName]: schema,
+    };
+    return true;
+  };
+  // Get all the route methods
+  const routeMethods = routeInfo.routes.map((route) => route.method);
+  // Check for localized paths
+  const hasLocalizationPath = routeInfo.routes.filter((route) =>
+    isLocalizedPath(route.path)
+  ).length;
+  // When the route methods contain any post or put requests
+  if (routeMethods.includes('POST') || routeMethods.includes('PUT')) {
+    const attributesToOmit = [
+      'createdAt',
+      'updatedAt',
+      'publishedAt',
+      'publishedBy',
+      'updatedBy',
+      'createdBy',
+      'localizations',
+    ];
+    const attributesForRequest = _.omit(attributes, attributesToOmit);
+
+    // Get a list of required attribute names
+    const requiredAttributes = Object.entries(attributesForRequest).reduce((acc, attribute) => {
+      const [attributeKey, attributeValue] = attribute;
+
+      if (attributeValue.required) {
+        acc.push(attributeKey);
+      }
+
+      return acc;
+    }, []);
+
+    if (hasLocalizationPath) {
+      schemas = {
+        ...schemas,
+        [`${pascalCase(uniqueName)}LocalizationRequest`]: {
+          required: [...requiredAttributes, 'locale'],
+          type: 'object',
+          properties: cleanSchemaAttributes(attributesForRequest, {
+            isRequest: true,
+            addComponentSchema,
+          }),
+        },
+      };
+    }
+
+    // Build the request schema
+    schemas = {
+      ...schemas,
+      [`${pascalCase(uniqueName)}Request`]: {
+        type: 'object',
+        required: ['data'],
+        properties: {
+          data: {
+            required: requiredAttributes,
+            type: 'object',
+            properties: cleanSchemaAttributes(attributesForRequest, {
+              isRequest: true,
+              addComponentSchema,
+            }),
+          },
+        },
+      },
+    };
+  }
+
+  if (hasLocalizationPath) {
+    schemas = {
+      ...schemas,
+      [`${pascalCase(uniqueName)}LocalizationResponse`]: {
+        type: 'object',
+        properties: {
+          id: { type: 'number' },
+          ...cleanSchemaAttributes(attributes, { addComponentSchema }),
+        },
+      },
+    };
+  }
+
+  // Check for routes that need to return a list
+  const hasListOfEntities = routeInfo.routes.filter((route) => hasFindMethod(route.handler)).length;
+  if (hasListOfEntities) {
+    // Build the list response schema
+    schemas = {
+      ...schemas,
+      [`${pascalCase(uniqueName)}ListResponseDataItem`]: {
+        type: 'object',
+        properties: {
+          id: { type: 'number' },
+          attributes: {
+            type: 'object',
+            properties: cleanSchemaAttributes(attributes, {
+              addComponentSchema,
+              componentSchemaRefName: `#/components/schemas/${pascalCase(
+                uniqueName
+              )}ListResponseDataItemLocalized`,
+            }),
+          },
+        },
+      },
+      [`${pascalCase(uniqueName)}ListResponseDataItemLocalized`]: {
+        type: 'object',
+        properties: {
+          id: { type: 'number' },
+          attributes: {
+            type: 'object',
+            properties: cleanSchemaAttributes(attributes, { addComponentSchema }),
+          },
+        },
+      },
+      [`${pascalCase(uniqueName)}ListResponse`]: {
+        properties: {
+          data: {
+            type: 'array',
+            items: {
+              $ref: `#/components/schemas/${pascalCase(uniqueName)}ListResponseDataItem`,
+            },
+          },
+          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)}ResponseDataObject`]: {
+      type: 'object',
+      properties: {
+        id: { type: 'number' },
+        attributes: {
+          type: 'object',
+          properties: cleanSchemaAttributes(attributes, {
+            addComponentSchema,
+            componentSchemaRefName: `#/components/schemas/${pascalCase(
+              uniqueName
+            )}ResponseDataObjectLocalized`,
+          }),
+        },
+      },
+    },
+    [`${pascalCase(uniqueName)}ResponseDataObjectLocalized`]: {
+      type: 'object',
+      properties: {
+        id: { type: 'number' },
+        attributes: {
+          type: 'object',
+          properties: cleanSchemaAttributes(attributes, { addComponentSchema }),
+        },
+      },
+    },
+    [`${pascalCase(uniqueName)}Response`]: {
+      properties: {
+        data: {
+          $ref: `#/components/schemas/${pascalCase(uniqueName)}ResponseDataObject`,
+        },
+        meta: { type: 'object' },
+      },
+    },
+  };
+  return { ...schemas, ...componentSchemas };
+};
+
+const buildComponentSchema = (api) => {
+  // A reusable loop for building paths and component schemas
+  // Uses the api param to build a new set of params for each content type
+  // Passes these new params to the function provided
+  return loopContentTypeNames(api, getAllSchemasForContentType);
+};
+
+module.exports = buildComponentSchema;

package/server/services/helpers/index.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const builApiEndpointPath = require('./build-api-endpoint-path');
+const buildComponentSchema = require('./build-component-schema');
+
+module.exports = {
+  builApiEndpointPath,
+  buildComponentSchema,
+};

package/server/services/helpers/utils/clean-schema-attributes.js

@@ -0,0 +1,235 @@
+'use strict';
+
+const _ = require('lodash');
+const getSchemaData = require('./get-schema-data');
+const pascalCase = require('./pascal-case');
+/**
+ * @description - Converts types found on attributes to OpenAPI acceptable data types
+ *
+ * @param {object} attributes - The attributes found on a contentType
+ * @param {{ typeMap: Map, isRequest: boolean, addComponentSchema: function, componentSchemaRefName: string }} opts
+ * @returns Attributes using OpenAPI acceptable data types
+ */
+const cleanSchemaAttributes = (
+  attributes,
+  {
+    typeMap = new Map(),
+    isRequest = false,
+    addComponentSchema = () => {},
+    componentSchemaRefName = '',
+  } = {}
+) => {
+  const attributesCopy = _.cloneDeep(attributes);
+
+  for (const prop of Object.keys(attributesCopy)) {
+    const attribute = attributesCopy[prop];
+    if (attribute.default) {
+      delete attributesCopy[prop].default;
+    }
+
+    switch (attribute.type) {
+      case 'password': {
+        if (!isRequest) {
+          delete attributesCopy[prop];
+          break;
+        }
+
+        attributesCopy[prop] = { type: 'string', format: 'password', example: '*******' };
+        break;
+      }
+      case 'email': {
+        attributesCopy[prop] = { type: 'string', format: 'email' };
+        break;
+      }
+      case 'string':
+      case 'text':
+      case 'richtext': {
+        attributesCopy[prop] = { type: 'string' };
+        break;
+      }
+      case 'timestamp': {
+        attributesCopy[prop] = { type: 'string', format: 'timestamp', example: Date.now() };
+        break;
+      }
+      case 'time': {
+        attributesCopy[prop] = { type: 'string', format: 'time', example: '12:54.000' };
+        break;
+      }
+      case 'date': {
+        attributesCopy[prop] = { type: 'string', format: 'date' };
+        break;
+      }
+      case 'datetime': {
+        attributesCopy[prop] = { type: 'string', format: 'date-time' };
+        break;
+      }
+      case 'boolean': {
+        attributesCopy[prop] = { type: 'boolean' };
+        break;
+      }
+      case 'enumeration': {
+        attributesCopy[prop] = { type: 'string', enum: attribute.enum };
+        break;
+      }
+      case 'decimal':
+      case 'float': {
+        attributesCopy[prop] = { type: 'number', format: 'float' };
+        break;
+      }
+      case 'integer': {
+        attributesCopy[prop] = { type: 'integer' };
+        break;
+      }
+      case 'biginteger': {
+        attributesCopy[prop] = { type: 'string', pattern: '^\\d*$', example: '123456789' };
+        break;
+      }
+      case 'json': {
+        attributesCopy[prop] = {};
+        break;
+      }
+      case 'uid': {
+        attributesCopy[prop] = { type: 'string' };
+        break;
+      }
+      case 'component': {
+        const componentAttributes = strapi.components[attribute.component].attributes;
+        const rawComponentSchema = {
+          type: 'object',
+          properties: {
+            ...(isRequest ? {} : { id: { type: 'number' } }),
+            ...cleanSchemaAttributes(componentAttributes, {
+              typeMap,
+              isRequest,
+            }),
+          },
+        };
+        const refComponentSchema = {
+          $ref: `#/components/schemas/${pascalCase(attribute.component)}Component`,
+        };
+        const componentExists = addComponentSchema(
+          `${pascalCase(attribute.component)}Component`,
+          rawComponentSchema
+        );
+        const finalComponentSchema = componentExists ? refComponentSchema : rawComponentSchema;
+        if (attribute.repeatable) {
+          attributesCopy[prop] = {
+            type: 'array',
+            items: finalComponentSchema,
+          };
+        } else {
+          attributesCopy[prop] = finalComponentSchema;
+        }
+        break;
+      }
+      case 'dynamiczone': {
+        const components = attribute.components.map((component) => {
+          const componentAttributes = strapi.components[component].attributes;
+          const rawComponentSchema = {
+            type: 'object',
+            properties: {
+              ...(isRequest ? {} : { id: { type: 'number' } }),
+              __component: { type: 'string' },
+              ...cleanSchemaAttributes(componentAttributes, {
+                typeMap,
+                isRequest,
+                addComponentSchema,
+              }),
+            },
+          };
+          const refComponentSchema = { $ref: `#/components/schemas/${pascalCase(component)}` };
+          const componentExists = addComponentSchema(pascalCase(component), rawComponentSchema);
+          const finalComponentSchema = componentExists ? refComponentSchema : rawComponentSchema;
+          return finalComponentSchema;
+        });
+
+        attributesCopy[prop] = {
+          type: 'array',
+          items: {
+            anyOf: components,
+          },
+        };
+        break;
+      }
+      case 'media': {
+        const imageAttributes = strapi.contentType('plugin::upload.file').attributes;
+        const isListOfEntities = attribute.multiple;
+
+        if (isRequest) {
+          const oneOfType = {
+            oneOf: [{ type: 'integer' }, { type: 'string' }],
+            example: 'string or id',
+          };
+
+          attributesCopy[prop] = isListOfEntities ? { type: 'array', items: oneOfType } : oneOfType;
+          break;
+        }
+
+        attributesCopy[prop] = {
+          type: 'object',
+          properties: {
+            data: getSchemaData(isListOfEntities, cleanSchemaAttributes(imageAttributes)),
+          },
+        };
+        break;
+      }
+
+      case 'relation': {
+        const isListOfEntities = attribute.relation.includes('ToMany');
+
+        if (isRequest) {
+          const oneOfType = {
+            oneOf: [{ type: 'integer' }, { type: 'string' }],
+            example: 'string or id',
+          };
+
+          attributesCopy[prop] = isListOfEntities ? { type: 'array', items: oneOfType } : oneOfType;
+          break;
+        }
+
+        if (prop === 'localizations') {
+          attributesCopy[prop] = {
+            type: 'object',
+            properties: {
+              data: {
+                type: 'array',
+                items: componentSchemaRefName.length ? { $ref: componentSchemaRefName } : {},
+              },
+            },
+          };
+          break;
+        }
+
+        if (!attribute.target || typeMap.has(attribute.target)) {
+          attributesCopy[prop] = {
+            type: 'object',
+            properties: { data: getSchemaData(isListOfEntities, {}) },
+          };
+          break;
+        }
+
+        typeMap.set(attribute.target, true);
+        const targetAttributes = strapi.contentType(attribute.target).attributes;
+
+        attributesCopy[prop] = {
+          type: 'object',
+          properties: {
+            data: getSchemaData(
+              isListOfEntities,
+              cleanSchemaAttributes(targetAttributes, { typeMap, isRequest })
+            ),
+          },
+        };
+
+        break;
+      }
+      default: {
+        throw new Error(`Invalid type ${attribute.type} while generating open api schema.`);
+      }
+    }
+  }
+
+  return attributesCopy;
+};
+
+module.exports = cleanSchemaAttributes;

package/server/services/helpers/utils/get-api-responses.js

@@ -0,0 +1,105 @@
+'use strict';
+
+const pascalCase = require('./pascal-case');
+
+/**
+ * @description - Builds the Swagger response object for a given api
+ *
+ * @param {object} name - Name of the api or plugin
+ * @param {object} route - The current route
+ * @param {boolean} isListOfEntities - Checks for a list of entitities
+ *
+ * @returns The Swagger responses
+ */
+const getApiResponse = ({
+  uniqueName,
+  route,
+  isListOfEntities = false,
+  isLocalizationPath = false,
+}) => {
+  const getSchema = () => {
+    if (route.method === 'DELETE') {
+      return {
+        type: 'integer',
+        format: 'int64',
+      };
+    }
+
+    if (isLocalizationPath) {
+      return { $ref: `#/components/schemas/${pascalCase(uniqueName)}LocalizationResponse` };
+    }
+
+    if (isListOfEntities) {
+      return { $ref: `#/components/schemas/${pascalCase(uniqueName)}ListResponse` };
+    }
+
+    return { $ref: `#/components/schemas/${pascalCase(uniqueName)}Response` };
+  };
+
+  const schema = getSchema();
+
+  return {
+    responses: {
+      200: {
+        description: 'OK',
+        content: {
+          'application/json': {
+            schema,
+          },
+        },
+      },
+      400: {
+        description: 'Bad Request',
+        content: {
+          'application/json': {
+            schema: {
+              $ref: '#/components/schemas/Error',
+            },
+          },
+        },
+      },
+      401: {
+        description: 'Unauthorized',
+        content: {
+          'application/json': {
+            schema: {
+              $ref: '#/components/schemas/Error',
+            },
+          },
+        },
+      },
+      403: {
+        description: 'Forbidden',
+        content: {
+          'application/json': {
+            schema: {
+              $ref: '#/components/schemas/Error',
+            },
+          },
+        },
+      },
+      404: {
+        description: 'Not Found',
+        content: {
+          'application/json': {
+            schema: {
+              $ref: '#/components/schemas/Error',
+            },
+          },
+        },
+      },
+      500: {
+        description: 'Internal Server Error',
+        content: {
+          'application/json': {
+            schema: {
+              $ref: '#/components/schemas/Error',
+            },
+          },
+        },
+      },
+    },
+  };
+};
+
+module.exports = getApiResponse;

package/server/services/helpers/utils/get-schema-data.js

@@ -0,0 +1,32 @@
+'use strict';
+
+/**
+ * @description Determines the format of the data response
+ * 
+ * @param {boolean} isListOfEntities - Checks for a multiple entities
+ * @param {object} attributes - The attributes found on a contentType
+ 
+ * @returns object | array of attributes
+ */
+module.exports = (isListOfEntities, attributes) => {
+  if (isListOfEntities) {
+    return {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'number' },
+          attributes: { type: 'object', properties: attributes },
+        },
+      },
+    };
+  }
+
+  return {
+    type: 'object',
+    properties: {
+      id: { type: 'number' },
+      attributes: { type: 'object', properties: attributes },
+    },
+  };
+};

package/server/services/helpers/utils/loop-content-type-names.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const _ = require('lodash');
+
+/**
+ * @description A reusable loop for building api endpoint paths and component schemas
+ *
+ * @param {object} api - Api information to pass to the callback
+ * @param {function} callback - Logic to execute for the given api
+ *
+ * @returns {object}
+ */
+const loopContentTypeNames = (api, callback) => {
+  let result = {};
+  for (const contentTypeName of api.ctNames) {
+    // Get the attributes found on the api's contentType
+    const uid = `${api.getter}::${api.name}.${contentTypeName}`;
+    const { attributes, info: contentTypeInfo } = strapi.contentType(uid);
+
+    // Get the routes for the current api
+    const routeInfo =
+      api.getter === 'plugin'
+        ? strapi.plugin(api.name).routes['content-api']
+        : strapi.api[api.name].routes[contentTypeName];
+
+    // Continue to next iteration if routeInfo is undefined
+    if (!routeInfo) continue;
+
+    // Uppercase the first letter of the api name
+    const apiName = _.upperFirst(api.name);
+
+    // Create a unique name if the api name and contentType name don't match
+    const uniqueName =
+      api.name === contentTypeName ? apiName : `${apiName} - ${_.upperFirst(contentTypeName)}`;
+
+    const apiInfo = {
+      ...api,
+      routeInfo,
+      attributes,
+      uniqueName,
+      contentTypeInfo,
+    };
+
+    result = {
+      ...result,
+      ...callback(apiInfo),
+    };
+  }
+
+  return result;
+};
+
+module.exports = loopContentTypeNames;

package/server/services/helpers/utils/pascal-case.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const _ = require('lodash');
+
+const pascalCase = (string) => {
+  return _.upperFirst(_.camelCase(string));
+};
+
+module.exports = pascalCase;