@strapi/plugin-documentation 4.10.0-beta.1 → 4.10.0

package/server/services/documentation.js

@@ -2,37 +2,50 @@
 
 const path = require('path');
 const fs = require('fs-extra');
-const _ = require('lodash');
+const { produce } = require('immer');
 const { getAbsoluteServerUrl } = require('@strapi/utils');
-
-const defaultPluginConfig = require('../config/default-plugin-config');
 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 registeredDocs = [];
+  const pluginsThatNeedDocumentation = getPluginsThatNeedDocumentation(config);
+  const overrideService = strapi.plugin('documentation').service('override');
 
   return {
-    registerDoc(doc) {
-      let registeredDoc = doc;
-      // parseYaml
-      if (typeof doc === 'string') {
-        registeredDoc = require('yaml').parse(registeredDoc);
-      }
-      // receive an object we can register it directly
-      registeredDocs.push(registeredDoc);
+    /**
+     *
+     * @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 _.get(config, 'info.version');
+      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');
     },
 
@@ -46,7 +59,8 @@ module.exports = ({ strapi }) => {
                 path.resolve(this.getFullDocumentationPath(), version, 'full_documentation.json')
               )
             );
-            const generatedDate = _.get(doc, ['info', 'x-generation-date'], null);
+
+            const generatedDate = doc.info['x-generation-date'];
 
             return { version, generatedDate, url: '' };
           } catch (err) {
@@ -99,8 +113,7 @@ module.exports = ({ strapi }) => {
     },
 
     getPluginAndApiInfo() {
-      const plugins = _.get(config, 'x-strapi-config.plugins');
-      const pluginsToDocument = plugins.map((plugin) => {
+      const pluginsToDocument = pluginsThatNeedDocumentation.map((plugin) => {
         return {
           name: plugin,
           getter: 'plugin',
@@ -119,92 +132,118 @@ module.exports = ({ strapi }) => {
       return [...apisToDocument, ...pluginsToDocument];
     },
 
-    async getCustomConfig() {
-      const customConfigPath = this.getCustomDocumentationPath();
-      const pathExists = await fs.pathExists(customConfigPath);
-      if (pathExists) {
-        return fs.readJson(customConfigPath);
-      }
-
-      return {};
-    },
-
     /**
      * @description - Creates the Swagger json files
      */
     async generateFullDoc(version = this.getDocumentationVersion()) {
-      let paths = {};
-      let schemas = {};
       const apis = this.getPluginAndApiInfo();
-      for (const api of apis) {
-        const apiName = api.name;
-        const apiDirPath = path.join(this.getApiDocumentationPath(api), version);
-
-        const apiDocPath = path.join(apiDirPath, `${apiName}.json`);
-
-        const apiPath = builApiEndpointPath(api);
+      const apisThatNeedGeneratedDocumentation = apis.filter(
+        ({ name }) => !overrideService.excludedFromGeneration.includes(name)
+      );
 
-        if (!apiPath) {
-          continue;
+      // 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 = getAbsoluteServerUrl(strapi.config);
+            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, apiPath, { spaces: 2 });
+        await fs.writeJson(apiDocPath, newApiPath, { spaces: 2 });
 
-        const componentSchema = buildComponentSchema(api);
+        generatedDocumentation = produce(generatedDocumentation, (draft) => {
+          if (generatedSchemas) {
+            draft.components = {
+              schemas: { ...draft.components.schemas, ...generatedSchemas },
+            };
+          }
 
-        schemas = {
-          ...schemas,
-          ...componentSchema,
-        };
+          if (newApiPath) {
+            draft.paths = { ...draft.paths, ...newApiPath };
+          }
+        });
+      }
 
-        paths = { ...paths, ...apiPath };
+      // 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'
       );
-
-      const defaultConfig = _.cloneDeep(defaultPluginConfig);
-
-      const serverUrl = getAbsoluteServerUrl(strapi.config);
-      const apiPath = strapi.config.get('api.rest.prefix');
-
-      _.set(defaultConfig, 'servers', [
-        {
-          url: `${serverUrl}${apiPath}`,
-          description: 'Development server',
-        },
-      ]);
-      _.set(defaultConfig, ['info', 'x-generation-date'], new Date().toISOString());
-      _.set(defaultConfig, ['info', 'version'], version);
-      _.merge(defaultConfig.components, { schemas });
-
-      const customConfig = await this.getCustomConfig();
-      const config = _.merge(defaultConfig, customConfig);
-
-      const finalDoc = { ...config, paths };
-
-      registeredDocs.forEach((doc) => {
-        // Add tags
-        finalDoc.tags = finalDoc.tags || [];
-        finalDoc.tags.push(...(doc.tags || []));
-
-        // Add Paths
-        _.assign(finalDoc.paths, doc.paths);
-
-        // Add components
-        _.forEach(doc.components || {}, (val, key) => {
-          finalDoc.components[key] = finalDoc.components[key] || {};
-
-          _.assign(finalDoc.components[key], val);
-        });
-      });
-
+      // Write the documentation to the file system
       await fs.ensureFile(fullDocJsonPath);
-      await fs.writeJson(fullDocJsonPath, finalDoc, { spaces: 2 });
+      await fs.writeJson(fullDocJsonPath, finalDocumentation, { spaces: 2 });
     },
   };
 };

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

@@ -81,7 +81,7 @@ const getPathWithPrefix = (prefix, route) => {
  *
  * @returns {object}
  */
-const getPaths = ({ routeInfo, uniqueName, contentTypeInfo }) => {
+const getPaths = ({ routeInfo, uniqueName, contentTypeInfo, kind }) => {
   // Get the routes for the current content type
   const contentTypeRoutes = routeInfo.routes.filter((route) => {
     return (
@@ -98,10 +98,11 @@ const getPaths = ({ routeInfo, uniqueName, contentTypeInfo }) => {
     const hasPathParams = route.path.includes('/:');
     const pathWithPrefix = getPathWithPrefix(routeInfo.prefix, route);
     const routePath = hasPathParams ? parsePathWithVariables(pathWithPrefix) : pathWithPrefix;
+
     const { responses } = getApiResponses({
       uniqueName,
       route,
-      isListOfEntities,
+      isListOfEntities: kind !== 'singleType' && isListOfEntities,
       isLocalizationPath,
     });
 

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

@@ -7,6 +7,18 @@ 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
  *
@@ -20,16 +32,17 @@ const { hasFindMethod, isLocalizedPath } = require('./utils/routes');
 const getAllSchemasForContentType = ({ routeInfo, attributes, uniqueName }) => {
   // Store response and request schemas in an object
   let schemas = {};
-  let componentSchemas = {};
+  let strapiComponentSchemas = {};
   // 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,
+  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
@@ -38,39 +51,31 @@ const getAllSchemasForContentType = ({ routeInfo, attributes, uniqueName }) => {
   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;
-    }, []);
 
+  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: [...requiredAttributes, 'locale'],
+          required: [...requiredRequestAttributes, 'locale'],
           type: 'object',
           properties: cleanSchemaAttributes(attributesForRequest, {
             isRequest: true,
-            addComponentSchema,
+            didAddStrapiComponentsToSchemas,
           }),
         },
       };
@@ -84,11 +89,11 @@ const getAllSchemasForContentType = ({ routeInfo, attributes, uniqueName }) => {
         required: ['data'],
         properties: {
           data: {
-            required: requiredAttributes,
+            ...(requiredRequestAttributes.length && { required: requiredRequestAttributes }),
             type: 'object',
             properties: cleanSchemaAttributes(attributesForRequest, {
               isRequest: true,
-              addComponentSchema,
+              didAddStrapiComponentsToSchemas,
             }),
           },
         },
@@ -96,14 +101,26 @@ const getAllSchemasForContentType = ({ routeInfo, attributes, uniqueName }) => {
     };
   }
 
+  // Build the localization response schema
   if (hasLocalizationPath) {
     schemas = {
       ...schemas,
-      [`${pascalCase(uniqueName)}LocalizationResponse`]: {
+      [`${pascalCase(uniqueName)}ResponseDataObjectLocalized`]: {
         type: 'object',
         properties: {
           id: { type: 'number' },
-          ...cleanSchemaAttributes(attributes, { addComponentSchema }),
+          attributes: {
+            $ref: `#/components/schemas/${pascalCase(uniqueName)}`,
+          },
+        },
+      },
+      [`${pascalCase(uniqueName)}LocalizationResponse`]: {
+        type: 'object',
+        properties: {
+          data: {
+            $ref: `#/components/schemas/${pascalCase(uniqueName)}ResponseDataObjectLocalized`,
+          },
+          meta: { type: 'object' },
         },
       },
     };
@@ -112,6 +129,46 @@ const getAllSchemasForContentType = ({ routeInfo, attributes, uniqueName }) => {
   // 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,
@@ -120,27 +177,12 @@ const getAllSchemasForContentType = ({ routeInfo, attributes, uniqueName }) => {
         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 }),
+            $ref: `#/components/schemas/${pascalCase(uniqueName)}`,
           },
         },
       },
       [`${pascalCase(uniqueName)}ListResponse`]: {
+        type: 'object',
         properties: {
           data: {
             type: 'array',
@@ -152,6 +194,7 @@ const getAllSchemasForContentType = ({ routeInfo, attributes, uniqueName }) => {
             type: 'object',
             properties: {
               pagination: {
+                type: 'object',
                 properties: {
                   page: { type: 'integer' },
                   pageSize: { type: 'integer', minimum: 25 },
@@ -166,35 +209,29 @@ const getAllSchemasForContentType = ({ routeInfo, attributes, uniqueName }) => {
     };
   }
 
+  const requiredAttributes = getRequiredAttributes(attributes);
   // Build the response schema
   schemas = {
     ...schemas,
-    [`${pascalCase(uniqueName)}ResponseDataObject`]: {
+    [`${pascalCase(uniqueName)}`]: {
       type: 'object',
-      properties: {
-        id: { type: 'number' },
-        attributes: {
-          type: 'object',
-          properties: cleanSchemaAttributes(attributes, {
-            addComponentSchema,
-            componentSchemaRefName: `#/components/schemas/${pascalCase(
-              uniqueName
-            )}ResponseDataObjectLocalized`,
-          }),
-        },
-      },
+      ...(requiredAttributes.length && { required: requiredAttributes }),
+      properties: cleanSchemaAttributes(attributes, {
+        didAddStrapiComponentsToSchemas,
+        componentSchemaRefName: `#/components/schemas/${pascalCase(uniqueName)}`,
+      }),
     },
-    [`${pascalCase(uniqueName)}ResponseDataObjectLocalized`]: {
+    [`${pascalCase(uniqueName)}ResponseDataObject`]: {
       type: 'object',
       properties: {
         id: { type: 'number' },
         attributes: {
-          type: 'object',
-          properties: cleanSchemaAttributes(attributes, { addComponentSchema }),
+          $ref: `#/components/schemas/${pascalCase(uniqueName)}`,
         },
       },
     },
     [`${pascalCase(uniqueName)}Response`]: {
+      type: 'object',
       properties: {
         data: {
           $ref: `#/components/schemas/${pascalCase(uniqueName)}ResponseDataObject`,
@@ -203,7 +240,8 @@ const getAllSchemasForContentType = ({ routeInfo, attributes, uniqueName }) => {
       },
     },
   };
-  return { ...schemas, ...componentSchemas };
+
+  return { ...schemas, ...strapiComponentSchemas };
 };
 
 const buildComponentSchema = (api) => {

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

@@ -7,7 +7,7 @@ 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
+ * @param {{ typeMap: Map, isRequest: boolean, didAddStrapiComponentsToSchemas: function, componentSchemaRefName: string }} opts
  * @returns Attributes using OpenAPI acceptable data types
  */
 const cleanSchemaAttributes = (
@@ -15,7 +15,7 @@ const cleanSchemaAttributes = (
   {
     typeMap = new Map(),
     isRequest = false,
-    addComponentSchema = () => {},
+    didAddStrapiComponentsToSchemas = () => {},
     componentSchemaRefName = '',
   } = {}
 ) => {
@@ -107,7 +107,7 @@ const cleanSchemaAttributes = (
         const refComponentSchema = {
           $ref: `#/components/schemas/${pascalCase(attribute.component)}Component`,
         };
-        const componentExists = addComponentSchema(
+        const componentExists = didAddStrapiComponentsToSchemas(
           `${pascalCase(attribute.component)}Component`,
           rawComponentSchema
         );
@@ -133,12 +133,17 @@ const cleanSchemaAttributes = (
               ...cleanSchemaAttributes(componentAttributes, {
                 typeMap,
                 isRequest,
-                addComponentSchema,
+                didAddStrapiComponentsToSchemas,
               }),
             },
           };
-          const refComponentSchema = { $ref: `#/components/schemas/${pascalCase(component)}` };
-          const componentExists = addComponentSchema(pascalCase(component), rawComponentSchema);
+          const refComponentSchema = {
+            $ref: `#/components/schemas/${pascalCase(component)}Component`,
+          };
+          const componentExists = didAddStrapiComponentsToSchemas(
+            `${pascalCase(component)}Component`,
+            rawComponentSchema
+          );
           const finalComponentSchema = componentExists ? refComponentSchema : rawComponentSchema;
           return finalComponentSchema;
         });
@@ -168,7 +173,10 @@ const cleanSchemaAttributes = (
         attributesCopy[prop] = {
           type: 'object',
           properties: {
-            data: getSchemaData(isListOfEntities, cleanSchemaAttributes(imageAttributes)),
+            data: getSchemaData(
+              isListOfEntities,
+              cleanSchemaAttributes(imageAttributes, { typeMap })
+            ),
           },
         };
         break;

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

@@ -15,7 +15,8 @@ const loopContentTypeNames = (api, callback) => {
   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);
+
+    const { attributes, info: contentTypeInfo, kind } = strapi.contentType(uid);
 
     // Get the routes for the current api
     const routeInfo =
@@ -39,6 +40,7 @@ const loopContentTypeNames = (api, callback) => {
       attributes,
       uniqueName,
       contentTypeInfo,
+      kind,
     };
 
     result = {

package/server/services/index.js

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