@strapi/plugin-documentation 5.0.0-beta.0 → 5.0.0-beta.1

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

@@ -1,246 +0,0 @@
-'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, didAddStrapiComponentsToSchemas: function, componentSchemaRefName: string }} opts
- * @returns Attributes using OpenAPI acceptable data types
- */
-const cleanSchemaAttributes = (
-  attributes,
-  {
-    typeMap = new Map(),
-    isRequest = false,
-    didAddStrapiComponentsToSchemas = () => {},
-    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':
-      case 'blocks': {
-        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 = didAddStrapiComponentsToSchemas(
-          `${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,
-                didAddStrapiComponentsToSchemas,
-              }),
-            },
-          };
-          const refComponentSchema = {
-            $ref: `#/components/schemas/${pascalCase(component)}Component`,
-          };
-          const componentExists = didAddStrapiComponentsToSchemas(
-            `${pascalCase(component)}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, { typeMap })
-            ),
-          },
-        };
-        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}ListResponseDataItemLocalized` }
-                  : {},
-              },
-            },
-          };
-          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

@@ -1,105 +0,0 @@
-'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

@@ -1,32 +0,0 @@
-'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

@@ -1,55 +0,0 @@
-'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, kind } = 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,
-      kind,
-    };
-
-    result = {
-      ...result,
-      ...callback(apiInfo),
-    };
-  }
-
-  return result;
-};
-
-module.exports = loopContentTypeNames;

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

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

package/server/services/helpers/utils/query-params.js

@@ -1,105 +0,0 @@
-'use strict';
-
-module.exports = [
-  {
-    name: 'sort',
-    in: 'query',
-    description: 'Sort by attributes ascending (asc) or descending (desc)',
-    deprecated: false,
-    required: false,
-    schema: {
-      type: 'string',
-    },
-  },
-  {
-    name: 'pagination[withCount]',
-    in: 'query',
-    description: 'Return page/pageSize (default: true)',
-    deprecated: false,
-    required: false,
-    schema: {
-      type: 'boolean',
-    },
-  },
-  {
-    name: 'pagination[page]',
-    in: 'query',
-    description: 'Page number (default: 0)',
-    deprecated: false,
-    required: false,
-    schema: {
-      type: 'integer',
-    },
-  },
-  {
-    name: 'pagination[pageSize]',
-    in: 'query',
-    description: 'Page size (default: 25)',
-    deprecated: false,
-    required: false,
-    schema: {
-      type: 'integer',
-    },
-  },
-  {
-    name: 'pagination[start]',
-    in: 'query',
-    description: 'Offset value (default: 0)',
-    deprecated: false,
-    required: false,
-    schema: {
-      type: 'integer',
-    },
-  },
-  {
-    name: 'pagination[limit]',
-    in: 'query',
-    description: 'Number of entities to return (default: 25)',
-    deprecated: false,
-    required: false,
-    schema: {
-      type: 'integer',
-    },
-  },
-  {
-    name: 'fields',
-    in: 'query',
-    description: 'Fields to return (ex: title,author)',
-    deprecated: false,
-    required: false,
-    schema: {
-      type: 'string',
-    },
-  },
-  {
-    name: 'populate',
-    in: 'query',
-    description: 'Relations to return',
-    deprecated: false,
-    required: false,
-    schema: {
-      type: 'string',
-    },
-  },
-  {
-    name: 'filters',
-    in: 'query',
-    description: 'Filters to apply',
-    deprecated: false,
-    required: false,
-    schema: {
-      type: 'object',
-    },
-    style: 'deepObject',
-  },
-  {
-    name: 'locale',
-    in: 'query',
-    description: 'Locale to apply',
-    deprecated: false,
-    required: false,
-    schema: {
-      type: 'string',
-    },
-  },
-];

package/server/services/helpers/utils/routes.js

@@ -1,10 +0,0 @@
-'use strict';
-
-const hasFindMethod = (handler) => handler.split('.').pop() === 'find';
-
-const isLocalizedPath = (routePath) => routePath.includes('localizations');
-
-module.exports = {
-  isLocalizedPath,
-  hasFindMethod,
-};

package/server/services/index.js

@@ -1,9 +0,0 @@
-'use strict';
-
-const documentation = require('./documentation');
-const override = require('./override');
-
-module.exports = {
-  documentation,
-  override,
-};

package/server/services/override.js

@@ -1,52 +0,0 @@
-'use strict';
-
-const { getPluginsThatNeedDocumentation } = require('./utils/get-plugins-that-need-documentation');
-
-module.exports = ({ strapi }) => {
-  const registeredOverrides = [];
-  const excludedFromGeneration = [];
-
-  return {
-    registeredOverrides,
-    excludedFromGeneration,
-    /**
-     *
-     * @param {(string | string[])} api - The name of the api or and array of apis to exclude from generation
-     */
-    excludeFromGeneration(api) {
-      if (Array.isArray(api)) {
-        excludedFromGeneration.push(...api);
-
-        return;
-      }
-
-      excludedFromGeneration.push(api);
-    },
-    /**
-     * @TODO pluginOrigin should be required in next major release
-     * @param {object} doc - The openapi specifcation to override
-     * @param {object} options - The options to override the documentation
-     * @param {(string | undefined)} options.pluginOrigin - The name of the plugin that is overriding the documentation
-     * @param {string[]} options.excludeFromGeneration - The list of apis or plugins to exclude from generation
-     */
-    registerOverride(override, { pluginOrigin, excludeFromGeneration = [] } = {}) {
-      const pluginsThatNeedDocumentation = getPluginsThatNeedDocumentation(
-        strapi.config.get('plugin::documentation')
-      );
-      // Don't apply the override if the plugin is not in the list of plugins that need documentation
-      if (pluginOrigin && !pluginsThatNeedDocumentation.includes(pluginOrigin)) return;
-
-      if (excludeFromGeneration.length) {
-        this.excludeFromGeneration(excludeFromGeneration);
-      }
-
-      let overrideToRegister = override;
-      // Parse yaml if we receive a string
-      if (typeof override === 'string') {
-        overrideToRegister = require('yaml').parse(overrideToRegister);
-      }
-      // receive an object we can register it directly
-      registeredOverrides.push(overrideToRegister);
-    },
-  };
-};

package/server/services/utils/default-openapi-components.js

@@ -1,40 +0,0 @@
-'use strict';
-
-module.exports = {
-  securitySchemes: {
-    bearerAuth: {
-      type: 'http',
-      scheme: 'bearer',
-      bearerFormat: 'JWT',
-    },
-  },
-  schemas: {
-    Error: {
-      type: 'object',
-      required: ['error'],
-      properties: {
-        data: {
-          nullable: true,
-          oneOf: [{ type: 'object' }, { type: 'array', items: { type: 'object' } }],
-        },
-        error: {
-          type: 'object',
-          properties: {
-            status: {
-              type: 'integer',
-            },
-            name: {
-              type: 'string',
-            },
-            message: {
-              type: 'string',
-            },
-            details: {
-              type: 'object',
-            },
-          },
-        },
-      },
-    },
-  },
-};

package/server/services/utils/get-plugins-that-need-documentation.js

@@ -1,24 +0,0 @@
-'use strict';
-
-const getPluginsThatNeedDocumentation = (config) => {
-  // Default plugins that need documentation generated
-  const defaultPlugins = ['upload', 'users-permissions'];
-
-  // User specified plugins that need documentation generated
-  const userPluginsConfig = config['x-strapi-config'].plugins;
-
-  if (userPluginsConfig === null) {
-    // The user hasn't specified any plugins to document, use the defaults
-    return defaultPlugins;
-  }
-
-  if (userPluginsConfig.length) {
-    // The user has specified certain plugins to document, use them
-    return userPluginsConfig;
-  }
-
-  // The user has specified that no plugins should be documented
-  return [];
-};
-
-module.exports = { getPluginsThatNeedDocumentation };