npm - @strapi/plugin-documentation - Versions diffs - 0.0.0-4fc90398602f - Mend

@strapi/plugin-documentation 0.0.0-4fc90398602f

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (72) hide show

package/LICENSE +22 -0
package/README.md +151 -0
package/__mocks__/strapi.js +41 -0
package/__tests__/build-component-schema.test.js +271 -0
package/admin/src/components/FieldActionWrapper/index.js +14 -0
package/admin/src/components/PluginIcon/index.js +12 -0
package/admin/src/index.js +80 -0
package/admin/src/pages/PluginPage/index.js +199 -0
package/admin/src/pages/PluginPage/tests/index.test.js +873 -0
package/admin/src/pages/PluginPage/tests/server.js +23 -0
package/admin/src/pages/SettingsPage/index.js +181 -0
package/admin/src/pages/SettingsPage/tests/index.test.js +612 -0
package/admin/src/pages/SettingsPage/tests/server.js +18 -0
package/admin/src/pages/utils/api.js +31 -0
package/admin/src/pages/utils/schema.js +11 -0
package/admin/src/pages/utils/useReactQuery.js +46 -0
package/admin/src/permissions.js +19 -0
package/admin/src/pluginId.js +5 -0
package/admin/src/translations/ar.json +20 -0
package/admin/src/translations/cs.json +21 -0
package/admin/src/translations/de.json +26 -0
package/admin/src/translations/dk.json +39 -0
package/admin/src/translations/en.json +39 -0
package/admin/src/translations/es.json +39 -0
package/admin/src/translations/fr.json +26 -0
package/admin/src/translations/id.json +24 -0
package/admin/src/translations/it.json +26 -0
package/admin/src/translations/ko.json +39 -0
package/admin/src/translations/ms.json +23 -0
package/admin/src/translations/nl.json +21 -0
package/admin/src/translations/pl.json +39 -0
package/admin/src/translations/pt-BR.json +21 -0
package/admin/src/translations/pt.json +21 -0
package/admin/src/translations/ru.json +28 -0
package/admin/src/translations/sk.json +24 -0
package/admin/src/translations/th.json +24 -0
package/admin/src/translations/tr.json +20 -0
package/admin/src/translations/uk.json +23 -0
package/admin/src/translations/vi.json +24 -0
package/admin/src/translations/zh-Hans.json +28 -0
package/admin/src/translations/zh.json +24 -0
package/admin/src/utils/getTrad.js +5 -0
package/admin/src/utils/index.js +2 -0
package/admin/src/utils/openWithNewTab.js +20 -0
package/package.json +62 -0
package/server/bootstrap.js +54 -0
package/server/config/default-plugin-config.js +74 -0
package/server/config/index.js +7 -0
package/server/controllers/documentation.js +241 -0
package/server/controllers/index.js +7 -0
package/server/index.js +17 -0
package/server/middlewares/documentation.js +25 -0
package/server/middlewares/index.js +7 -0
package/server/middlewares/restrict-access.js +24 -0
package/server/public/index.html +70 -0
package/server/public/login.html +145 -0
package/server/register.js +11 -0
package/server/routes/index.js +84 -0
package/server/services/documentation.js +209 -0
package/server/services/helpers/build-api-endpoint-path.js +185 -0
package/server/services/helpers/build-component-schema.js +159 -0
package/server/services/helpers/index.js +9 -0
package/server/services/helpers/utils/clean-schema-attributes.js +212 -0
package/server/services/helpers/utils/get-api-responses.js +105 -0
package/server/services/helpers/utils/get-schema-data.js +32 -0
package/server/services/helpers/utils/loop-content-type-names.js +53 -0
package/server/services/helpers/utils/pascal-case.js +9 -0
package/server/services/helpers/utils/query-params.js +84 -0
package/server/services/helpers/utils/routes.js +10 -0
package/server/services/index.js +7 -0
package/strapi-admin.js +3 -0
package/strapi-server.js +3 -0

package/server/public/index.html ADDED Viewed

@@ -0,0 +1,70 @@
+<!-- HTML for static distribution bundle build --><!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Swagger UI</title>
+    <link
+      rel="stylesheet"
+      type="text/css"
+      href="<%=backendUrl%>/plugins/documentation/swagger-ui.css"
+    />
+    <link
+      rel="icon"
+      type="image/png"
+      href="<%=backendUrl%>/plugins/documentation/favicon-32x32.png"
+      sizes="32x32"
+    />
+    <link
+      rel="icon"
+      type="image/png"
+      href="<%=backendUrl%>/plugins/documentation/favicon-16x16.png"
+      sizes="16x16"
+    />
+    <style>
+      html {
+        box-sizing: border-box;
+        overflow: -moz-scrollbars-vertical;
+        overflow-y: scroll;
+      }
+      *,
+      *:before,
+      *:after {
+        box-sizing: inherit;
+      }
+      body {
+        margin: 0;
+        background: #fafafa;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script class="custom-swagger-ui">
+      window.onload = function() {
+        const ui = SwaggerUIBundle({
+          url: "https://petstore.swagger.io/v2/swagger.json",
+          spec: <%=spec%>,
+          dom_id: '#swagger-ui',
+          docExpansion: "none",
+          deepLinking: true,
+          presets: [
+            SwaggerUIBundle.presets.apis,
+            SwaggerUIStandalonePreset,
+          ],
+          plugins: [
+            SwaggerUIBundle.plugins.DownloadUrl,
+          ],
+          layout: "StandaloneLayout",
+        });
+        window.ui = ui;
+      }
+    </script>
+    <script src="<%=backendUrl%>/plugins/documentation/swagger-ui-bundle.js"></script>
+    <script src="<%=backendUrl%>/plugins/documentation/swagger-ui-standalone-preset.js"></script>
+  </body>
+</html>

package/server/public/login.html ADDED Viewed

@@ -0,0 +1,145 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Login - Documentation</title>
+    <link href="https://fonts.googleapis.com/css?family=Lato:400,700" rel="stylesheet" />
+    <style>
+      html {
+        font-size: 62.5%;
+        height: 100%;
+        margin: 0;
+        padding: 0;
+      }
+      body {
+        height: 100%;
+        margin: 0;
+        background-color: #ffffff;
+        font-family: 'Lato';
+        font-size: 1.4rem;
+        font-weight: 400;
+        text-rendering: optimizeLegibility;
+        -webkit-font-smoothing: antialiased;
+        -moz-osx-font-smoothing: grayscale;
+      }
+      .login {
+        height: 100%;
+        background-color: #f6f9fc;
+      }
+      .login .login-form {
+        height: calc(100% - 70px);
+        padding: 68px 0 0;
+        text-align: center;
+      }
+      .login .login-form form {
+        position: relative;
+        max-width: 460px;
+        padding: 26px 30px;
+        margin: 55px auto 0;
+        background-color: #ffffff;
+        border-radius: 3px;
+        box-shadow: 0px 2px 4px rgba(91, 107, 174, 0.15);
+        text-align: center;
+      }
+      .login .login-form form:before {
+        position: absolute;
+        content: '';
+        top: 0px;
+        left: 0;
+        display: inline-block;
+        width: 100%;
+        height: 2px;
+        background-color: #2b66cc;
+      }
+      .login .login-form form .error {
+        display: block;
+        color: #ff4e00;
+        padding-bottom: 20px;
+      }
+      .login .login-form .sub-title {
+        margin-top: 35px;
+        font-size: 1.6rem;
+        font-weight: 400;
+      }
+      .login .login-form .logo {
+        max-height: 40px;
+      }
+      .login .login-form form label {
+        display: block;
+        margin-bottom: 18px;
+        width: 100%;
+        text-align: left;
+        font-weight: 600;
+      }
+      .login .login-form form input {
+        outline: none;
+        width: calc(100% - 30px);
+        height: 36px;
+        padding: 0 15px;
+        border: 1px solid #ececec;
+        border-radius: 2px;
+        margin-bottom: 20px;
+        line-height: 36px;
+        text-align: left;
+      }
+      .login .login-form form input[type='submit'] {
+        cursor: pointer;
+        display: inline-block;
+        width: auto;
+        margin: 12px auto 0;
+        padding: 0 75px;
+        background: transparent;
+        border-radius: 36px;
+        border: 1px solid #2b66cc;
+        color: #2b66cc;
+        text-transform: uppercase;
+        font-size: 1.4rem;
+        font-weight: 700;
+        transition: all 0.2s ease-out;
+      }
+      .login .login-form form input[type='submit']:hover {
+        background: #2b66cc;
+        color: #ffffff;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="login">
+      <section class="login-form">
+        <div class="container">
+          <div class="row">
+            <div class="col-lg-6 col-lg-offset-3 col-md-12">
+              <img
+                alt="Strapi logo"
+                class="logo"
+                src="https://strapi.io/assets/images/logo_login.png"
+              />
+              <h2 class="sub-title">Enter the password to access the documentation.</h2>
+              <form method="post" action="<%=actionUrl%>">
+                <span class="error">Wrong password...</span>
+                <label>Password</label>
+                <input
+                  type="password"
+                  name="password"
+                  placeholder="&#x2022;&#x2022;&#x2022;&#x2022;&#x2022;&#x2022;&#x2022;&#x2022;&#x2022;"
+                />
+                <input type="submit" value="Login" />
+              </form>
+            </div>
+          </div>
+        </div>
+      </section>
+    </div>
+  </body>
+</html>

package/server/register.js ADDED Viewed

@@ -0,0 +1,11 @@
+'use strict';
+const registerDocumentationMiddleWare = require('./middlewares/documentation');
+/**
+ * Register upload plugin
+ * @param {{ strapi: import('@strapi/strapi').Strapi }}
+ */
+module.exports = async ({ strapi }) => {
+  await registerDocumentationMiddleWare({ strapi });
+};

package/server/routes/index.js ADDED Viewed

@@ -0,0 +1,84 @@
+'use strict';
+const restrictAccess = require('../middlewares/restrict-access');
+module.exports = [
+  {
+    method: 'GET',
+    path: '/',
+    handler: 'documentation.index',
+    config: {
+      auth: false,
+      middlewares: [restrictAccess],
+    },
+  },
+  {
+    method: 'GET',
+    path: '/v:major(\\d+).:minor(\\d+).:patch(\\d+)',
+    handler: 'documentation.index',
+    config: {
+      auth: false,
+      middlewares: [restrictAccess],
+    },
+  },
+  {
+    method: 'GET',
+    path: '/login',
+    handler: 'documentation.loginView',
+    config: {
+      auth: false,
+    },
+  },
+  {
+    method: 'POST',
+    path: '/login',
+    handler: 'documentation.login',
+    config: {
+      auth: false,
+    },
+  },
+  {
+    method: 'GET',
+    path: '/getInfos',
+    handler: 'documentation.getInfos',
+    config: {
+      policies: [
+        { name: 'admin::hasPermissions', config: { actions: ['plugin::documentation.read'] } },
+      ],
+    },
+  },
+  {
+    method: 'POST',
+    path: '/regenerateDoc',
+    handler: 'documentation.regenerateDoc',
+    config: {
+      policies: [
+        {
+          name: 'admin::hasPermissions',
+          config: { actions: ['plugin::documentation.settings.regenerate'] },
+        },
+      ],
+    },
+  },
+  {
+    method: 'PUT',
+    path: '/updateSettings',
+    handler: 'documentation.updateSettings',
+    config: {
+      policies: [
+        {
+          name: 'admin::hasPermissions',
+          config: { actions: ['plugin::documentation.settings.update'] },
+        },
+      ],
+    },
+  },
+  {
+    method: 'DELETE',
+    path: '/deleteDoc/:version',
+    handler: 'documentation.deleteDoc',
+    config: {
+      policies: [],
+    },
+  },
+];

package/server/services/documentation.js ADDED Viewed

@@ -0,0 +1,209 @@
+'use strict';
+const path = require('path');
+const fs = require('fs-extra');
+const _ = require('lodash');
+const { getAbsoluteServerUrl } = require('@strapi/utils');
+const defaultPluginConfig = require('../config/default-plugin-config');
+const { builApiEndpointPath, buildComponentSchema } = require('./helpers');
+module.exports = ({ strapi }) => {
+  const config = strapi.config.get('plugin.documentation');
+  const registeredDocs = [];
+  return {
+    registerDoc(doc) {
+      // parseYaml
+      if (typeof doc === 'string') {
+        doc = require('yaml').parse(doc);
+      }
+      // receive an object we can register it directly
+      registeredDocs.push(doc);
+    },
+    getDocumentationVersion() {
+      return _.get(config, 'info.version');
+    },
+    getFullDocumentationPath() {
+      return path.join(strapi.dirs.app.extensions, 'documentation', 'documentation');
+    },
+    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 = _.get(doc, ['info', 'x-generation-date'], null);
+            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 plugins = _.get(config, 'x-strapi-config.plugins');
+      const pluginsToDocument = plugins.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];
+    },
+    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);
+        if (!apiPath) {
+          continue;
+        }
+        await fs.ensureFile(apiDocPath);
+        await fs.writeJson(apiDocPath, apiPath, { spaces: 2 });
+        const componentSchema = buildComponentSchema(api);
+        schemas = {
+          ...schemas,
+          ...componentSchema,
+        };
+        paths = { ...paths, ...apiPath };
+      }
+      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);
+        });
+      });
+      await fs.ensureFile(fullDocJsonPath);
+      await fs.writeJson(fullDocJsonPath, finalDoc, { spaces: 2 });
+    },
+  };
+};

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

@@ -0,0 +1,185 @@
+'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: 'string' },
+      };
+    });
+};
+/**
+ *
+ * @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 }) => {
+  // 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,
+      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;