@strapi/plugin-documentation 4.2.0-beta.1 → 4.2.0-beta.4

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

@@ -0,0 +1,156 @@
+'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 = {};
+  // 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 }),
+        },
+      };
+    }
+
+    // Build the request schema
+    schemas = {
+      ...schemas,
+      [`${pascalCase(uniqueName)}Request`]: {
+        type: 'object',
+        required: ['data'],
+        properties: {
+          data: {
+            required: requiredAttributes,
+            type: 'object',
+            properties: cleanSchemaAttributes(attributesForRequest, { isRequest: true }),
+          },
+        },
+      },
+    };
+  }
+
+  if (hasLocalizationPath) {
+    schemas = {
+      ...schemas,
+      [`${pascalCase(uniqueName)}LocalizationResponse`]: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          ...cleanSchemaAttributes(attributes),
+        },
+      },
+    };
+  }
+
+  // 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)}ListResponse`]: {
+        type: 'object',
+        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)}Response`]: {
+      type: 'object',
+      properties: {
+        data: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+            attributes: { type: 'object', properties: cleanSchemaAttributes(attributes) },
+          },
+        },
+        meta: { type: 'object' },
+      },
+    },
+  };
+
+  return schemas;
+};
+
+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/{utils → services/helpers/utils}/clean-schema-attributes.js

@@ -4,13 +4,12 @@ const _ = require('lodash');
 const getSchemaData = require('./get-schema-data');
 
 /**
- * @description - Converts types found on attributes to OpenAPI specific data types
+ * @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 }} opts
  * @returns Attributes using OpenAPI acceptable data types
  */
-
 const cleanSchemaAttributes = (attributes, { typeMap = new Map(), isRequest = false } = {}) => {
   const attributesCopy = _.cloneDeep(attributes);
 
@@ -170,6 +169,14 @@ const cleanSchemaAttributes = (attributes, { typeMap = new Map(), isRequest = fa
           break;
         }
 
+        if (prop === 'localizations') {
+          attributesCopy[prop] = {
+            type: 'array',
+            items: { type: 'object', properties: {} },
+          };
+          break;
+        }
+
         if (!attribute.target || typeMap.has(attribute.target)) {
           attributesCopy[prop] = {
             type: 'object',

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/loop-content-type-names.js

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

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

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

package/yarn-error.log

@@ -0,0 +1,95 @@
+Arguments: 
+  /Users/alex/.nvm/versions/node/v16.13.2/bin/node /Users/alex/.nvm/versions/node/v16.13.2/bin/yarn
+
+PATH: 
+  /Users/alex/.nvm/versions/node/v16.13.2/bin:/Users/alex/.nvm/versions/node/v18.1.0/bin:/Users/alex/.nvm/versions/node/v16.13.2/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/go/bin:/Users/alex/.nvm/versions/node/v16.13.2/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/Users/alex/.yarn/bin:/Users/alex/.yarn/bin
+
+Yarn version: 
+  1.22.17
+
+Node version: 
+  16.13.2
+
+Platform: 
+  darwin arm64
+
+Trace: 
+  SyntaxError: /Users/alex/dev/strapi/strapi/packages/plugins/documentation/package.json: Unexpected token < in JSON at position 1187
+      at JSON.parse (<anonymous>)
+      at /Users/alex/.nvm/versions/node/v16.13.2/lib/node_modules/yarn/lib/cli.js:1625:59
+      at Generator.next (<anonymous>)
+      at step (/Users/alex/.nvm/versions/node/v16.13.2/lib/node_modules/yarn/lib/cli.js:310:30)
+      at /Users/alex/.nvm/versions/node/v16.13.2/lib/node_modules/yarn/lib/cli.js:321:13
+
+npm manifest: 
+  {
+    "name": "@strapi/plugin-documentation",
+    "version": "4.1.12",
+    "description": "Create an OpenAPI Document and visualize your API with SWAGGER UI.",
+    "repository": {
+      "type": "git",
+      "url": "https://github.com/strapi/strapi.git",
+      "directory": "packages/plugins/documentation"
+    },
+    "license": "SEE LICENSE IN LICENSE",
+    "author": {
+      "name": "Strapi Solutions SAS",
+      "email": "hi@strapi.io",
+      "url": "https://strapi.io"
+    },
+    "maintainers": [
+      {
+        "name": "Strapi Solutions SAS",
+        "email": "hi@strapi.io",
+        "url": "https://strapi.io"
+      }
+    ],
+    "scripts": {
+      "test": "echo \"no tests yet\""
+    },
+    "dependencies": {
+      "@strapi/helper-plugin": "4.1.12",
+      "@strapi/utils": "4.1.12",
+      "bcryptjs": "2.4.3",
+      "cheerio": "^1.0.0-rc.5",
+      "fs-extra": "10.0.0",
+      "koa-static": "^5.0.0",
+      "lodash": "4.17.21",
+      "path-to-regexp": "6.2.0",
+      "pluralize": "8.0.0",
+      "react": "^17.0.2",
+      "react-copy-to-clipboard": "^5.0.3",
+      "react-dom": "^17.0.2",
+      "react-intl": "5.20.2",
+      "react-redux": "7.2.3",
+      "react-router": "^5.2.0",
+      "react-router-dom": "5.2.0",
+      "redux": "^4.0.1",
+      "reselect": "^4.0.0",
+  <<<<<<< HEAD
+      "swagger-ui-dist": "3.47.1",
+      "yaml": "1.10.2"
+  =======
+      "swagger-ui-dist": "4.11.1"
+  >>>>>>> master
+    },
+    "peerDependencies": {
+      "@strapi/strapi": "^4.0.0"
+    },
+    "engines": {
+      "node": ">=12.22.0 <=16.x.x",
+      "npm": ">=6.0.0"
+    },
+    "strapi": {
+      "displayName": "Documentation",
+      "name": "documentation",
+      "description": "Create an OpenAPI Document and visualize your API with SWAGGER UI.",
+      "kind": "plugin"
+    }
+  }
+
+yarn manifest: 
+  No manifest
+
+Lockfile: 
+  No lockfile

package/server/services/utils/components.json

@@ -1,25 +0,0 @@
-{
-  "components": {
-    "securitySchemes": {
-      "bearerAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "bearerFormat": "JWT"
-      }
-    },
-    "schemas": {
-      "Error": {
-        "required": ["code", "message"],
-        "properties": {
-          "code": {
-            "type": "integer",
-            "format": "int32"
-          },
-          "message": {
-            "type": "string"
-          }
-        }
-      }
-    }
-  }
-}

package/server/services/utils/parametersOptions.json

@@ -1,134 +0,0 @@
-[
-  {
-    "name": "_limit",
-    "in": "query",
-    "required": false,
-    "description": "Maximum number of results possible",
-    "schema": {
-      "type": "integer"
-    },
-    "deprecated": false
-  },
-  {
-    "name": "_sort",
-    "in": "query",
-    "required": false,
-    "description": "Sort according to a specific field.",
-    "schema": {
-      "type": "string"
-    },
-    "deprecated": false
-  },
-  {
-    "name": "_start",
-    "in": "query",
-    "required": false,
-    "description": "Skip a specific number of entries (especially useful for pagination)",
-    "schema": {
-      "type": "integer"
-    },
-    "deprecated": false
-  },
-  {
-    "name": "=",
-    "in": "query",
-    "required": false,
-    "description": "Get entries that matches exactly your input",
-    "schema": {
-      "type": "string"
-    },
-    "deprecated": false
-  },
-  {
-    "name": "_ne",
-    "in": "query",
-    "required": false,
-    "description": "Get records that are not equals to something",
-    "schema": {
-      "type": "string"
-    },
-    "deprecated": false
-  },
-  {
-    "name": "_lt",
-    "in": "query",
-    "required": false,
-    "description": "Get record that are lower than a value",
-    "schema": {
-      "type": "string"
-    },
-    "deprecated": false
-  },
-  {
-    "name": "_lte",
-    "in": "query",
-    "required": false,
-    "description": "Get records that are lower than or equal to a value",
-    "schema": {
-      "type": "string"
-    },
-    "deprecated": false
-  },
-  {
-    "name": "_gt",
-    "in": "query",
-    "required": false,
-    "description": "Get records that are greater than a value",
-    "schema": {
-      "type": "string"
-    },
-    "deprecated": false
-  },
-  {
-    "name": "_gte",
-    "in": "query",
-    "required": false,
-    "description": "Get records that are greater than  or equal a value",
-    "schema": {
-      "type": "string"
-    },
-    "deprecated": false
-  },
-  {
-    "name": "_contains",
-    "in": "query",
-    "required": false,
-    "description": "Get records that contains a value",
-    "schema": {
-      "type": "string"
-    },
-    "deprecated": false
-  },
-  {
-    "name": "_containss",
-    "in": "query",
-    "required": false,
-    "description": "Get records that contains (case sensitive) a value",
-    "schema": {
-      "type": "string"
-    },
-    "deprecated": false
-  },
-  {
-    "name": "_in",
-    "in": "query",
-    "required": false,
-    "description": "Get records that matches any value in the array of values",
-    "schema": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "deprecated": false
-  },
-  {
-    "name": "_nin",
-    "in": "query",
-    "required": false,
-    "description": "Get records that doesn't match any value in the array of values",
-    "schema": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
-    "deprecated": false
-  }
-]

package/server/services/utils/unknownComponent.json

@@ -1,11 +0,0 @@
-{
-  "components": {
-    "schemas": {
-      "Foo": {
-        "properties": {
-          "bar": "string"
-        }
-      }
-    }
-  }
-}