@strapi/plugin-documentation 4.0.0-next.9 → 4.0.3

package/server/utils/builders/build-api-endpoint-path.js

@@ -0,0 +1,174 @@
+'use strict';
+
+const _ = require('lodash');
+const pathToRegexp = require('path-to-regexp');
+
+const queryParams = require('../query-params');
+const buildApiRequests = require('./build-api-requests');
+const buildApiResponses = require('./build-api-responses');
+
+/**
+ * @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: 'string' },
+      };
+    });
+};
+
+/**
+ *
+ * @param {string} prefix - The route prefix
+ * @param {string} path - The route path
+ *
+ * @returns {string}
+ */
+const getPathWithPrefix = (prefix, path) => {
+  if (path.includes('localizations')) {
+    return path;
+  }
+
+  if (path.endsWith('/')) {
+    return prefix;
+  }
+
+  return prefix.concat(path);
+};
+
+/**
+ *
+ * @param {object} api - Information about the api
+ * @param {object} api.routeInfo - The routes for a given api or plugin
+ * @param {string} api.routeInfo.prefix - The prefix for all routes
+ * @param {array}  api.routeInfo.routes - The routes for the current api
+ * @param {object} api.attributes - The attributes for a given api or plugin
+ * @param {string} api.tag - A descriptor for OpenAPI
+ *
+ * @returns {object}
+ */
+const getPaths = ({ routeInfo, attributes, tag }) => {
+  const paths = routeInfo.routes.reduce((acc, route) => {
+    // TODO: Find a more reliable way to determine list of entities vs a single entity
+    const isListOfEntities = route.handler.split('.').pop() === 'find';
+    const methodVerb = route.method.toLowerCase();
+
+    const hasPathParams = route.path.includes('/:');
+    const pathWithPrefix = routeInfo.prefix
+      ? getPathWithPrefix(routeInfo.prefix, route.path)
+      : route.path;
+    const routePath = hasPathParams ? parsePathWithVariables(pathWithPrefix) : pathWithPrefix;
+
+    const { responses } = buildApiResponses(attributes, route, isListOfEntities);
+
+    const swaggerConfig = {
+      responses,
+      tags: [_.upperFirst(tag)],
+      parameters: [],
+      requestBody: {},
+    };
+
+    if (isListOfEntities) {
+      swaggerConfig.parameters.push(...queryParams);
+    }
+
+    if (hasPathParams) {
+      const pathParams = getPathParams(route.path);
+      swaggerConfig.parameters.push(...pathParams);
+    }
+
+    if (['post', 'put'].includes(methodVerb)) {
+      const { requestBody } = buildApiRequests(attributes, route);
+
+      swaggerConfig.requestBody = requestBody;
+    }
+
+    _.set(acc, `${routePath}.${methodVerb}`, swaggerConfig);
+
+    return acc;
+  }, {});
+
+  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}
+ */
+module.exports = api => {
+  if (!api.ctNames.length && api.getter === 'plugin') {
+    // Set arbitrary attributes
+    const attributes = { foo: { type: 'string' } };
+    const routeInfo = strapi.plugin(api.name).routes['admin'];
+
+    const apiInfo = {
+      routeInfo,
+      attributes,
+      tag: api.name,
+    };
+
+    return getPaths(apiInfo);
+  }
+
+  // An api could have multiple contentTypes
+  for (const contentTypeName of api.ctNames) {
+    // Get the attributes found on the api's contentType
+    const uid = `${api.getter}::${api.name}.${contentTypeName}`;
+    const ct = strapi.contentType(uid);
+    const attributes = ct.attributes;
+
+    // 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];
+
+    // Parse an identifier for OpenAPI tag if the api name and contentType name don't match
+    const tag = api.name === contentTypeName ? api.name : `${api.name} - ${contentTypeName}`;
+    const apiInfo = {
+      routeInfo,
+      attributes,
+      tag,
+    };
+
+    return getPaths(apiInfo);
+  }
+};

package/server/utils/builders/build-api-requests.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const cleanSchemaAttributes = require('../clean-schema-attributes');
+
+/**
+ *
+ * @param {object} attributes - The attributes found on a contentType
+ * @param {object} route - The current route
+ *
+ * @returns The Swagger requestBody
+ */
+module.exports = (attributes, route) => {
+  const requiredAttributes = Object.entries(attributes)
+    .filter(([, attribute]) => attribute.required)
+    .map(([attributeName, attribute]) => {
+      return { [attributeName]: attribute };
+    });
+
+  const requestAttributes =
+    route.method === 'POST' && requiredAttributes.length
+      ? Object.assign({}, ...requiredAttributes)
+      : attributes;
+
+  return {
+    requestBody: {
+      required: true,
+      content: {
+        'application/json': {
+          schema: {
+            properties: {
+              data: {
+                type: 'object',
+                properties: cleanSchemaAttributes(requestAttributes, { isRequest: true }),
+              },
+            },
+          },
+        },
+      },
+    },
+  };
+};

package/server/utils/builders/build-api-responses.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const getSchemaData = require('../get-schema-data');
+const cleanSchemaAttributes = require('../clean-schema-attributes');
+const errorResponse = require('../error-response');
+
+/**
+ *
+ * @param {boolean} isSingleEntity - Checks for a single entity
+ * @returns {object} The correctly formatted meta object
+ */
+const getMeta = isListOfEntities => {
+  if (isListOfEntities) {
+    return {
+      type: 'object',
+      properties: {
+        pagination: {
+          properties: {
+            page: { type: 'integer' },
+            pageSize: { type: 'integer', minimum: 25 },
+            pageCount: { type: 'integer', maximum: 1 },
+            total: { type: 'integer' },
+          },
+        },
+      },
+    };
+  }
+
+  return { type: 'object' };
+};
+
+/**
+ * @description - Builds the Swagger response object for a given api
+ *
+ * @param {object} attributes - The attributes found on a contentType
+ * @param {object} route - The current route
+ * @param {boolean} isListOfEntities - Checks for a list of entitities
+ *
+ * @returns The Swagger responses
+ */
+module.exports = (attributes, route, isListOfEntities = false) => {
+  let schema;
+  if (route.method === 'DELETE') {
+    schema = {
+      type: 'integer',
+      format: 'int64',
+    };
+  } else {
+    schema = {
+      properties: {
+        data: getSchemaData(isListOfEntities, cleanSchemaAttributes(attributes)),
+        meta: getMeta(isListOfEntities),
+      },
+    };
+  }
+
+  return {
+    responses: {
+      '200': {
+        content: {
+          'application/json': {
+            schema,
+          },
+        },
+      },
+      '400': {
+        description: 'Bad Request',
+        content: {
+          'application/json': {
+            schema: errorResponse,
+          },
+        },
+      },
+      '401': {
+        description: 'Unauthorized',
+        content: {
+          'application/json': {
+            schema: errorResponse,
+          },
+        },
+      },
+      '403': {
+        description: 'Forbidden',
+        content: {
+          'application/json': {
+            schema: errorResponse,
+          },
+        },
+      },
+      '404': {
+        description: 'Not Found',
+        content: {
+          'application/json': {
+            schema: errorResponse,
+          },
+        },
+      },
+      '500': {
+        description: 'Internal Server Error',
+        content: {
+          'application/json': {
+            schema: errorResponse,
+          },
+        },
+      },
+    },
+  };
+};

package/server/utils/builders/index.js

@@ -0,0 +1,11 @@
+'use strict';
+
+const buildApiResponses = require('./build-api-responses');
+const buildApiRequests = require('./build-api-requests');
+const builApiEndpointPath = require('./build-api-endpoint-path');
+
+module.exports = {
+  buildApiResponses,
+  buildApiRequests,
+  builApiEndpointPath,
+};

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

@@ -0,0 +1,205 @@
+'use strict';
+
+const _ = require('lodash');
+const getSchemaData = require('./get-schema-data');
+
+/**
+ * @description - Converts types found on attributes to OpenAPI specific 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);
+
+  for (const prop in 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;
+
+        if (attribute.repeatable) {
+          attributesCopy[prop] = {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                ...(isRequest ? {} : { id: { type: 'string' } }),
+                ...cleanSchemaAttributes(componentAttributes, { typeMap, isRequest }),
+              },
+            },
+          };
+        } else {
+          attributesCopy[prop] = {
+            type: 'object',
+            properties: {
+              ...(isRequest ? {} : { id: { type: 'string' } }),
+              ...cleanSchemaAttributes(componentAttributes, {
+                typeMap,
+                isRequest,
+              }),
+            },
+          };
+        }
+        break;
+      }
+      case 'dynamiczone': {
+        const components = attribute.components.map(component => {
+          const componentAttributes = strapi.components[component].attributes;
+          return {
+            type: 'object',
+            properties: {
+              ...(isRequest ? {} : { id: { type: 'string' } }),
+              __component: { type: 'string' },
+              ...cleanSchemaAttributes(componentAttributes, { typeMap, isRequest }),
+            },
+          };
+        });
+
+        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 (!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/utils/error-response.js

@@ -0,0 +1,22 @@
+'use strict';
+
+module.exports = {
+  type: 'object',
+  required: ['error'],
+  properties: {
+    error: {
+      type: 'object',
+      properties: {
+        status: {
+          type: 'integer',
+        },
+        name: {
+          type: 'string',
+        },
+        message: {
+          type: 'string',
+        },
+      },
+    },
+  },
+};

package/server/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: 'string' },
+          attributes: { type: 'object', properties: attributes },
+        },
+      },
+    };
+  }
+
+  return {
+    type: 'object',
+    properties: {
+      id: { type: 'string' },
+      attributes: { type: 'object', properties: attributes },
+    },
+  };
+};

package/server/utils/query-params.js

@@ -0,0 +1,84 @@
+'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: 'Retun 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',
+    },
+  },
+];

package/strapi-admin.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./admin/src').default;

package/strapi-server.js

@@ -1,21 +1,3 @@
 'use strict';
 
-const bootstrap = require('./server/bootstrap');
-const policies = require('./server/policies');
-const services = require('./server/services');
-const routes = require('./server/routes');
-const controllers = require('./server/controllers');
-const middlewares = require('./server/middlewares');
-const config = require('./server/config');
-
-module.exports = () => {
-  return {
-    bootstrap,
-    config,
-    routes,
-    controllers,
-    middlewares,
-    policies,
-    services,
-  };
-};
+module.exports = require('./server');