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

package/server/services/documentation.js

@@ -1,246 +0,0 @@
-'use strict';
-
-const path = require('path');
-const fs = require('fs-extra');
-const { produce } = require('immer');
-const { builApiEndpointPath, buildComponentSchema } = require('./helpers');
-
-const defaultOpenApiComponents = require('./utils/default-openapi-components');
-const { getPluginsThatNeedDocumentation } = require('./utils/get-plugins-that-need-documentation');
-
-module.exports = ({ strapi }) => {
-  const config = strapi.config.get('plugin::documentation');
-  const pluginsThatNeedDocumentation = getPluginsThatNeedDocumentation(config);
-  const overrideService = strapi.plugin('documentation').service('override');
-
-  return {
-    /**
-     *
-     * @deprecated
-     * registerDoc is deprecated it will be removed in the next major release,
-     * use strapi.plugin('documentation').service('override').registerOverride() instead
-     * @param {object} doc - The openapi specifcation to override
-     * @param {object} options - The options to override the documentation
-     * @param {string} options.pluginOrigin - The name of the plugin that is overriding the documentation
-     * @param {string[]} options.excludeFromGeneration - The name of the plugin that is overriding the documentation
-     */
-    registerDoc(doc, options) {
-      strapi.log.warn(
-        "@strapi/plugin-documentation has deprecated registerDoc, use strapi.plugin('documentation').service('override').registerOverride() instead"
-      );
-      overrideService.registerOverride(doc, options);
-    },
-
-    getDocumentationVersion() {
-      return config.info.version;
-    },
-
-    getFullDocumentationPath() {
-      return path.join(strapi.dirs.app.extensions, 'documentation', 'documentation');
-    },
-
-    /**
-     *
-     * @deprecated
-     * This method will be removed in the next major release
-     */
-    getCustomDocumentationPath() {
-      return path.join(strapi.dirs.app.extensions, 'documentation', 'config', 'settings.json');
-    },
-
-    getDocumentationVersions() {
-      return fs
-        .readdirSync(this.getFullDocumentationPath())
-        .map((version) => {
-          try {
-            const doc = JSON.parse(
-              fs.readFileSync(
-                path.resolve(this.getFullDocumentationPath(), version, 'full_documentation.json')
-              )
-            );
-
-            const generatedDate = doc.info['x-generation-date'];
-
-            return { version, generatedDate, url: '' };
-          } catch (err) {
-            return null;
-          }
-        })
-        .filter((x) => x);
-    },
-
-    /**
-     * Returns settings stored in core-store
-     */
-    async getDocumentationAccess() {
-      const { restrictedAccess } = await strapi
-        .store({
-          environment: '',
-          type: 'plugin',
-          name: 'documentation',
-          key: 'config',
-        })
-        .get();
-
-      return { restrictedAccess };
-    },
-
-    /**
-     * @description - Gets the path for an api or plugin
-     *
-     * @param {object} api
-     * @property {string} api.name - Name of the api
-     * @property {string} api.getter - api | plugin
-     *
-     * @returns path to the api | plugin
-     */
-    getApiDocumentationPath(api) {
-      if (api.getter === 'plugin') {
-        return path.join(strapi.dirs.app.extensions, api.name, 'documentation');
-      }
-
-      return path.join(strapi.dirs.app.api, api.name, 'documentation');
-    },
-
-    async deleteDocumentation(version) {
-      const apis = this.getPluginAndApiInfo();
-      for (const api of apis) {
-        await fs.remove(path.join(this.getApiDocumentationPath(api), version));
-      }
-
-      await fs.remove(path.join(this.getFullDocumentationPath(), version));
-    },
-
-    getPluginAndApiInfo() {
-      const pluginsToDocument = pluginsThatNeedDocumentation.map((plugin) => {
-        return {
-          name: plugin,
-          getter: 'plugin',
-          ctNames: Object.keys(strapi.plugin(plugin).contentTypes),
-        };
-      });
-
-      const apisToDocument = Object.keys(strapi.api).map((api) => {
-        return {
-          name: api,
-          getter: 'api',
-          ctNames: Object.keys(strapi.api[api].contentTypes),
-        };
-      });
-
-      return [...apisToDocument, ...pluginsToDocument];
-    },
-
-    /**
-     * @description - Creates the Swagger json files
-     */
-    async generateFullDoc(version = this.getDocumentationVersion()) {
-      const apis = this.getPluginAndApiInfo();
-      const apisThatNeedGeneratedDocumentation = apis.filter(
-        ({ name }) => !overrideService.excludedFromGeneration.includes(name)
-      );
-
-      // Initialize the generated documentation with defaults
-      let generatedDocumentation = produce(
-        {
-          ...config,
-          components: defaultOpenApiComponents,
-        },
-        (draft) => {
-          if (draft.servers.length === 0) {
-            // When no servers found set the defaults
-            const serverUrl = strapi.config.get('server.absoluteUrl');
-            const apiPath = strapi.config.get('api.rest.prefix');
-            draft.servers = [
-              {
-                url: `${serverUrl}${apiPath}`,
-                description: 'Development server',
-              },
-            ];
-          }
-          // Set the generated date
-          draft.info['x-generation-date'] = new Date().toISOString();
-          // Set the plugins that need documentation
-          draft['x-strapi-config'].plugins = pluginsThatNeedDocumentation;
-          // Delete the mutateDocumentation key from the config so it doesn't end up in the spec
-          delete draft['x-strapi-config'].mutateDocumentation;
-        }
-      );
-      // Generate the documentation for each api and update the generatedDocumentation
-      for (const api of apisThatNeedGeneratedDocumentation) {
-        const apiName = api.name;
-
-        const newApiPath = builApiEndpointPath(api);
-        const generatedSchemas = buildComponentSchema(api);
-
-        // TODO: To be confirmed, do we still need to write these files...?
-        const apiDirPath = path.join(this.getApiDocumentationPath(api), version);
-        const apiDocPath = path.join(apiDirPath, `${apiName}.json`);
-        await fs.ensureFile(apiDocPath);
-        await fs.writeJson(apiDocPath, newApiPath, { spaces: 2 });
-
-        generatedDocumentation = produce(generatedDocumentation, (draft) => {
-          if (generatedSchemas) {
-            draft.components.schemas = { ...draft.components.schemas, ...generatedSchemas };
-          }
-
-          if (newApiPath) {
-            draft.paths = { ...draft.paths, ...newApiPath };
-          }
-        });
-      }
-
-      // When overrides are present update the generatedDocumentation
-      if (overrideService.registeredOverrides.length > 0) {
-        generatedDocumentation = produce(generatedDocumentation, (draft) => {
-          overrideService.registeredOverrides.forEach((override) => {
-            // Only run the overrrides when no override version is provided,
-            // or when the generated documentation version matches the override version
-            if (!override?.info?.version || override.info.version === version) {
-              if (override.tags) {
-                // Merge override tags with the generated tags
-                draft.tags = draft.tags || [];
-                draft.tags.push(...override.tags);
-              }
-
-              if (override.paths) {
-                // Merge override paths with the generated paths
-                // The override will add a new path or replace the value of an existing path
-                draft.paths = { ...draft.paths, ...override.paths };
-              }
-
-              if (override.components) {
-                Object.entries(override.components).forEach(([overrideKey, overrideValue]) => {
-                  draft.components[overrideKey] = draft.components[overrideKey] || {};
-                  // Merge override components with the generated components,
-                  // The override will add a new component or replace the value of an existing component
-                  draft.components[overrideKey] = {
-                    ...draft.components[overrideKey],
-                    ...overrideValue,
-                  };
-                });
-              }
-            }
-          });
-        });
-      }
-
-      // Escape hatch, allow the user to provide a mutateDocumentation function that can alter any part of
-      // the generated documentation before it is written to the file system
-      const userMutatesDocumentation = config['x-strapi-config'].mutateDocumentation;
-      const finalDocumentation = userMutatesDocumentation
-        ? produce(generatedDocumentation, userMutatesDocumentation)
-        : generatedDocumentation;
-
-      // Get the file path for the final documentation
-      const fullDocJsonPath = path.join(
-        this.getFullDocumentationPath(),
-        version,
-        'full_documentation.json'
-      );
-      // Write the documentation to the file system
-      await fs.ensureFile(fullDocJsonPath);
-      await fs.writeJson(fullDocJsonPath, finalDocumentation, { spaces: 2 });
-    },
-  };
-};

package/server/services/helpers/build-api-endpoint-path.js

@@ -1,186 +0,0 @@
-'use strict';
-
-const _ = require('lodash');
-const pathToRegexp = require('path-to-regexp');
-
-const pascalCase = require('./utils/pascal-case');
-const queryParams = require('./utils/query-params');
-const loopContentTypeNames = require('./utils/loop-content-type-names');
-const getApiResponses = require('./utils/get-api-responses');
-const { hasFindMethod, isLocalizedPath } = require('./utils/routes');
-
-/**
- * @description Parses a route with ':variable'
- *
- * @param {string} routePath - The route's path property
- * @returns {string}
- */
-const parsePathWithVariables = (routePath) => {
-  return pathToRegexp
-    .parse(routePath)
-    .map((token) => {
-      if (_.isObject(token)) {
-        return `${token.prefix}{${token.name}}`;
-      }
-
-      return token;
-    })
-    .join('');
-};
-
-/**
- * @description Builds the required object for a path parameter
- *
- * @param {string} routePath - The route's path property
- *
- * @returns {object } Swagger path params object
- */
-const getPathParams = (routePath) => {
-  return pathToRegexp
-    .parse(routePath)
-    .filter((token) => _.isObject(token))
-    .map((param) => {
-      return {
-        name: param.name,
-        in: 'path',
-        description: '',
-        deprecated: false,
-        required: true,
-        schema: { type: 'number' },
-      };
-    });
-};
-
-/**
- *
- * @param {string} prefix - The prefix found on the routes object
- * @param {string} route - The current route
- * @property {string} route.path - The current route's path
- * @property {object} route.config - The current route's config object
- *
- * @returns {string}
- */
-const getPathWithPrefix = (prefix, route) => {
-  // When the prefix is set on the routes and
-  // the current route is not trying to remove it
-  if (prefix && !_.has(route.config, 'prefix')) {
-    // Add the prefix to the path
-    return prefix.concat(route.path);
-  }
-
-  // Otherwise just return path
-  return route.path;
-};
-/**
- * @description Gets all paths based on routes
- *
- * @param {object} apiInfo
- * @property {object} apiInfo.routeInfo - The api routes object
- * @property {string} apiInfo.uniqueName - Content type name | Api name + Content type name
- * @property {object} apiInfo.contentTypeInfo - The info object found on content type schemas
- *
- * @returns {object}
- */
-const getPaths = ({ routeInfo, uniqueName, contentTypeInfo, kind }) => {
-  // Get the routes for the current content type
-  const contentTypeRoutes = routeInfo.routes.filter((route) => {
-    return (
-      route.path.includes(contentTypeInfo.pluralName) ||
-      route.path.includes(contentTypeInfo.singularName)
-    );
-  });
-
-  const paths = contentTypeRoutes.reduce((acc, route) => {
-    // TODO: Find a more reliable way to determine list of entities vs a single entity
-    const isListOfEntities = hasFindMethod(route.handler);
-    const isLocalizationPath = isLocalizedPath(route.path);
-    const methodVerb = route.method.toLowerCase();
-    const hasPathParams = route.path.includes('/:');
-    const pathWithPrefix = getPathWithPrefix(routeInfo.prefix, route);
-    const routePath = hasPathParams ? parsePathWithVariables(pathWithPrefix) : pathWithPrefix;
-
-    const { responses } = getApiResponses({
-      uniqueName,
-      route,
-      isListOfEntities: kind !== 'singleType' && isListOfEntities,
-      isLocalizationPath,
-    });
-
-    const swaggerConfig = {
-      responses,
-      tags: [_.upperFirst(uniqueName)],
-      parameters: [],
-      operationId: `${methodVerb}${routePath}`,
-    };
-
-    if (isListOfEntities) {
-      swaggerConfig.parameters.push(...queryParams);
-    }
-
-    if (hasPathParams) {
-      const pathParams = getPathParams(route.path);
-      swaggerConfig.parameters.push(...pathParams);
-    }
-
-    if (['post', 'put'].includes(methodVerb)) {
-      const refName = isLocalizationPath ? 'LocalizationRequest' : 'Request';
-      const requestBody = {
-        required: true,
-        content: {
-          'application/json': {
-            schema: {
-              $ref: `#/components/schemas/${pascalCase(uniqueName)}${refName}`,
-            },
-          },
-        },
-      };
-
-      swaggerConfig.requestBody = requestBody;
-    }
-
-    _.set(acc, `${routePath}.${methodVerb}`, swaggerConfig);
-
-    return acc;
-  }, {});
-
-  return paths;
-};
-
-/**
- * @decription Gets all open api paths object for a given content type
- *
- * @param {object} apiInfo
- *
- * @returns {object} Open API paths
- */
-const getAllPathsForContentType = (apiInfo) => {
-  let paths = {};
-
-  const pathsObject = getPaths(apiInfo);
-
-  paths = {
-    ...paths,
-    ...pathsObject,
-  };
-
-  return paths;
-};
-
-/**
- * @description - Builds the Swagger paths object for each api
- *
- * @param {object} api - Information about the current api
- * @property {string} api.name - The name of the api
- * @property {string} api.getter - The getter for the api (api | plugin)
- * @property {array} api.ctNames - The name of all contentTypes found on the api
- *
- * @returns {object}
- */
-const buildApiEndpointPath = (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, getAllPathsForContentType);
-};
-
-module.exports = buildApiEndpointPath;

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

@@ -1,254 +0,0 @@
-'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');
-
-const getRequiredAttributes = (allAttributes) => {
-  return Object.entries(allAttributes).reduce((acc, attribute) => {
-    const [attributeKey, attributeValue] = attribute;
-
-    if (attributeValue.required) {
-      acc.push(attributeKey);
-    }
-
-    return acc;
-  }, []);
-};
-
-/**
- * @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 strapiComponentSchemas = {};
-  // adds a ComponentSchema to the Schemas so it can be used as Ref
-  const didAddStrapiComponentsToSchemas = (schemaName, schema) => {
-    if (!Object.keys(schema) || !Object.keys(schema.properties)) return false;
-
-    // Add the Strapi components to the schema
-    strapiComponentSchemas = {
-      ...strapiComponentSchemas,
-      [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;
-
-  const attributesToOmit = [
-    'createdAt',
-    'updatedAt',
-    'publishedAt',
-    'publishedBy',
-    'updatedBy',
-    'createdBy',
-    'localizations',
-  ];
-  const attributesForRequest = _.omit(attributes, attributesToOmit);
-  // Get a list of required attribute names
-  const requiredRequestAttributes = getRequiredAttributes(attributesForRequest);
-  // Build the request schemas when the route has POST or PUT methods
-  if (routeMethods.includes('POST') || routeMethods.includes('PUT')) {
-    // Build localization requests schemas
-    if (hasLocalizationPath) {
-      schemas = {
-        ...schemas,
-        [`${pascalCase(uniqueName)}LocalizationRequest`]: {
-          required: [...requiredRequestAttributes, 'locale'],
-          type: 'object',
-          properties: cleanSchemaAttributes(attributesForRequest, {
-            isRequest: true,
-            didAddStrapiComponentsToSchemas,
-          }),
-        },
-      };
-    }
-
-    // Build the request schema
-    schemas = {
-      ...schemas,
-      [`${pascalCase(uniqueName)}Request`]: {
-        type: 'object',
-        required: ['data'],
-        properties: {
-          data: {
-            ...(requiredRequestAttributes.length && { required: requiredRequestAttributes }),
-            type: 'object',
-            properties: cleanSchemaAttributes(attributesForRequest, {
-              isRequest: true,
-              didAddStrapiComponentsToSchemas,
-            }),
-          },
-        },
-      },
-    };
-  }
-
-  // Build the localization response schema
-  if (hasLocalizationPath) {
-    schemas = {
-      ...schemas,
-      [`${pascalCase(uniqueName)}ResponseDataObjectLocalized`]: {
-        type: 'object',
-        properties: {
-          id: { type: 'number' },
-          attributes: {
-            $ref: `#/components/schemas/${pascalCase(uniqueName)}`,
-          },
-        },
-      },
-      [`${pascalCase(uniqueName)}LocalizationResponse`]: {
-        type: 'object',
-        properties: {
-          data: {
-            $ref: `#/components/schemas/${pascalCase(uniqueName)}ResponseDataObjectLocalized`,
-          },
-          meta: { type: 'object' },
-        },
-      },
-    };
-  }
-
-  // Check for routes that need to return a list
-  const hasListOfEntities = routeInfo.routes.filter((route) => hasFindMethod(route.handler)).length;
-  if (hasListOfEntities) {
-    // Buld the localized list response schema
-    if (hasLocalizationPath) {
-      schemas = {
-        ...schemas,
-        [`${pascalCase(uniqueName)}ListResponseDataItemLocalized`]: {
-          type: 'object',
-          properties: {
-            id: { type: 'number' },
-            attributes: {
-              $ref: `#/components/schemas/${pascalCase(uniqueName)}`,
-            },
-          },
-        },
-        [`${pascalCase(uniqueName)}LocalizationListResponse`]: {
-          type: 'object',
-          properties: {
-            data: {
-              type: 'array',
-              items: {
-                $ref: `#/components/schemas/${pascalCase(uniqueName)}ListResponseDataItemLocalized`,
-              },
-            },
-            meta: {
-              type: 'object',
-              properties: {
-                pagination: {
-                  type: 'object',
-                  properties: {
-                    page: { type: 'integer' },
-                    pageSize: { type: 'integer', minimum: 25 },
-                    pageCount: { type: 'integer', maximum: 1 },
-                    total: { type: 'integer' },
-                  },
-                },
-              },
-            },
-          },
-        },
-      };
-    }
-    // Build the list response schema
-    schemas = {
-      ...schemas,
-      [`${pascalCase(uniqueName)}ListResponseDataItem`]: {
-        type: 'object',
-        properties: {
-          id: { type: 'number' },
-          attributes: {
-            $ref: `#/components/schemas/${pascalCase(uniqueName)}`,
-          },
-        },
-      },
-      [`${pascalCase(uniqueName)}ListResponse`]: {
-        type: 'object',
-        properties: {
-          data: {
-            type: 'array',
-            items: {
-              $ref: `#/components/schemas/${pascalCase(uniqueName)}ListResponseDataItem`,
-            },
-          },
-          meta: {
-            type: 'object',
-            properties: {
-              pagination: {
-                type: 'object',
-                properties: {
-                  page: { type: 'integer' },
-                  pageSize: { type: 'integer', minimum: 25 },
-                  pageCount: { type: 'integer', maximum: 1 },
-                  total: { type: 'integer' },
-                },
-              },
-            },
-          },
-        },
-      },
-    };
-  }
-
-  const requiredAttributes = getRequiredAttributes(attributes);
-  // Build the response schema
-  schemas = {
-    ...schemas,
-    [`${pascalCase(uniqueName)}`]: {
-      type: 'object',
-      ...(requiredAttributes.length && { required: requiredAttributes }),
-      properties: cleanSchemaAttributes(attributes, {
-        didAddStrapiComponentsToSchemas,
-        componentSchemaRefName: `#/components/schemas/${pascalCase(uniqueName)}`,
-      }),
-    },
-    [`${pascalCase(uniqueName)}ResponseDataObject`]: {
-      type: 'object',
-      properties: {
-        id: { type: 'number' },
-        attributes: {
-          $ref: `#/components/schemas/${pascalCase(uniqueName)}`,
-        },
-      },
-    },
-    [`${pascalCase(uniqueName)}Response`]: {
-      type: 'object',
-      properties: {
-        data: {
-          $ref: `#/components/schemas/${pascalCase(uniqueName)}ResponseDataObject`,
-        },
-        meta: { type: 'object' },
-      },
-    },
-  };
-
-  return { ...schemas, ...strapiComponentSchemas };
-};
-
-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

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