@strapi/plugin-documentation 4.0.0-next.6 → 4.0.0

package/server/controllers/documentation.js

@@ -0,0 +1,240 @@
+'use strict';
+
+/**
+ * Documentation.js controller
+ *
+ * @description: A set of functions called "actions" of the `documentation` plugin.
+ */
+
+// Core dependencies.
+const path = require('path');
+const bcrypt = require('bcryptjs');
+
+// Public dependencies.
+const fs = require('fs-extra');
+const _ = require('lodash');
+const koaStatic = require('koa-static');
+
+module.exports = {
+  async getInfos(ctx) {
+    try {
+      const docService = strapi.plugin('documentation').service('documentation');
+      const docVersions = docService.getDocumentationVersions();
+      const documentationAccess = await docService.getDocumentationAccess();
+
+      ctx.send({
+        docVersions,
+        currentVersion: docService.getDocumentationVersion(),
+        prefix: strapi.plugin('documentation').config('x-strapi-config').path,
+        documentationAccess,
+      });
+    } catch (err) {
+      ctx.badRequest(null, err.message);
+    }
+  },
+
+  async index(ctx, next) {
+    try {
+      /**
+       * We don't expose the specs using koa-static or something else due to security reasons.
+       * That's why, we need to read the file localy and send the specs through it when we serve the Swagger UI.
+       */
+      const { major, minor, patch } = ctx.params;
+      const version =
+        major && minor && patch
+          ? `${major}.${minor}.${patch}`
+          : strapi
+              .plugin('documentation')
+              .service('documentation')
+              .getDocumentationVersion();
+
+      const openAPISpecsPath = path.join(
+        strapi.dirs.extensions,
+        'documentation',
+        'documentation',
+        version,
+        'full_documentation.json'
+      );
+
+      try {
+        const documentation = fs.readFileSync(openAPISpecsPath, 'utf8');
+        const layout = fs.readFileSync(
+          path.resolve(__dirname, '..', 'public', 'index.html'),
+          'utf8'
+        );
+        const filledLayout = _.template(layout)({
+          backendUrl: strapi.config.server.url,
+          spec: JSON.stringify(JSON.parse(documentation)),
+        });
+
+        try {
+          const layoutPath = path.resolve(
+            strapi.dirs.extensions,
+            'documentation',
+            'public',
+            'index.html'
+          );
+          await fs.ensureFile(layoutPath);
+          await fs.writeFile(layoutPath, filledLayout);
+
+          // Serve the file.
+          ctx.url = path.basename(`${ctx.url}/index.html`);
+
+          try {
+            const staticFolder = path.resolve(strapi.dirs.extensions, 'documentation', 'public');
+            return koaStatic(staticFolder)(ctx, next);
+          } catch (e) {
+            strapi.log.error(e);
+          }
+        } catch (e) {
+          strapi.log.error(e);
+        }
+      } catch (e) {
+        strapi.log.error(e);
+      }
+    } catch (e) {
+      strapi.log.error(e);
+    }
+  },
+
+  async loginView(ctx, next) {
+    // lazy require cheerio
+    const cheerio = require('cheerio');
+
+    const { error } = ctx.query;
+
+    try {
+      const layout = fs.readFileSync(path.join(__dirname, '..', 'public', 'login.html'));
+      const filledLayout = _.template(layout)({
+        actionUrl: `${strapi.config.server.url}${
+          strapi.config.get('plugin.documentation.x-strapi-config').path
+        }/login`,
+      });
+      const $ = cheerio.load(filledLayout);
+
+      $('.error').text(_.isEmpty(error) ? '' : 'Wrong password...');
+
+      try {
+        const layoutPath = path.resolve(
+          strapi.dirs.extensions,
+          'documentation',
+          'public',
+          'login.html'
+        );
+        await fs.ensureFile(layoutPath);
+        await fs.writeFile(layoutPath, $.html());
+
+        ctx.url = path.basename(`${ctx.url}/login.html`);
+
+        try {
+          const staticFolder = path.resolve(strapi.dirs.extensions, 'documentation', 'public');
+          return koaStatic(staticFolder)(ctx, next);
+        } catch (e) {
+          strapi.log.error(e);
+        }
+      } catch (e) {
+        strapi.log.error(e);
+      }
+    } catch (e) {
+      strapi.log.error(e);
+    }
+  },
+
+  async login(ctx) {
+    const {
+      body: { password },
+    } = ctx.request;
+
+    const { password: hash } = await strapi
+      .store({ type: 'plugin', name: 'documentation', key: 'config' })
+      .get();
+
+    const isValid = await bcrypt.compare(password, hash);
+
+    let querystring = '?error=password';
+
+    if (isValid) {
+      ctx.session.documentation = {
+        logged: true,
+      };
+
+      querystring = '';
+    }
+
+    ctx.redirect(
+      `${strapi.config.server.url}${
+        strapi.config.get('plugin.documentation.x-strapi-config').path
+      }${querystring}`
+    );
+  },
+
+  async regenerateDoc(ctx) {
+    const { version } = ctx.request.body;
+
+    const service = strapi.service('plugin::documentation.documentation');
+
+    const documentationVersions = service.getDocumentationVersions().map(el => el.version);
+
+    if (_.isEmpty(version)) {
+      return ctx.badRequest('Please provide a version.');
+    }
+
+    if (!documentationVersions.includes(version)) {
+      return ctx.badRequest('The version you are trying to generate does not exist.');
+    }
+
+    try {
+      strapi.reload.isWatching = false;
+      await service.generateFullDoc(version);
+      ctx.send({ ok: true });
+    } finally {
+      strapi.reload.isWatching = true;
+    }
+  },
+
+  async deleteDoc(ctx) {
+    const { version } = ctx.params;
+
+    const service = strapi.service('plugin::documentation.documentation');
+
+    const documentationVersions = service.getDocumentationVersions().map(el => el.version);
+
+    if (_.isEmpty(version)) {
+      return ctx.badRequest('Please provide a version.');
+    }
+
+    if (!documentationVersions.includes(version)) {
+      return ctx.badRequest('The version you are trying to delete does not exist.');
+    }
+
+    try {
+      strapi.reload.isWatching = false;
+      await service.deleteDocumentation(version);
+      ctx.send({ ok: true });
+    } finally {
+      strapi.reload.isWatching = true;
+    }
+  },
+
+  async updateSettings(ctx) {
+    const { restrictedAccess, password } = ctx.request.body;
+
+    const pluginStore = strapi.store({ type: 'plugin', name: 'documentation' });
+
+    const config = {
+      restrictedAccess: Boolean(restrictedAccess),
+    };
+
+    if (restrictedAccess) {
+      if (_.isEmpty(password)) {
+        return ctx.badRequest('Please provide a password');
+      }
+
+      config.password = await bcrypt.hash(password, 10);
+    }
+
+    await pluginStore.set({ key: 'config', value: config });
+
+    return ctx.send({ ok: true });
+  },
+};

package/server/controllers/index.js

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

package/server/index.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const bootstrap = require('./bootstrap');
+const services = require('./services');
+const routes = require('./routes');
+const controllers = require('./controllers');
+const register = require('./register');
+const config = require('./config');
+
+module.exports = () => ({
+  bootstrap,
+  config,
+  routes,
+  controllers,
+  register,
+  services,
+});

package/server/middlewares/documentation.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const path = require('path');
+const koaStatic = require('koa-static');
+const session = require('koa-session');
+const swaggerUi = require('swagger-ui-dist');
+
+module.exports = async ({ strapi }) => {
+  const sessionConfig = strapi.config.get('plugin.documentation').session;
+  strapi.server.app.keys = sessionConfig.secretKeys;
+  strapi.server.app.use(session(sessionConfig, strapi.server.app));
+
+  strapi.server.routes([
+    {
+      method: 'GET',
+      path: '/plugins/documentation/(.*)',
+      async handler(ctx, next) {
+        ctx.url = path.basename(ctx.url);
+
+        return koaStatic(swaggerUi.getAbsoluteFSPath(), {
+          maxage: 86400000,
+          defer: true,
+        })(ctx, next);
+      },
+      config: {
+        auth: false,
+      },
+    },
+  ]);
+};

package/server/middlewares/index.js

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

package/server/middlewares/restrict-access.js

@@ -0,0 +1,24 @@
+'use strict';
+
+module.exports = async (ctx, next) => {
+  const pluginStore = strapi.store({ type: 'plugin', name: 'documentation' });
+
+  const config = await pluginStore.get({ key: 'config' });
+
+  if (!config.restrictedAccess) {
+    return next();
+  }
+
+  if (!ctx.session.documentation || !ctx.session.documentation.logged) {
+    const querystring = ctx.querystring ? `?${ctx.querystring}` : '';
+
+    return ctx.redirect(
+      `${strapi.config.server.url}${
+        strapi.config.get('plugin.documentation.x-strapi-config').path
+      }/login${querystring}`
+    );
+  }
+
+  // Execute the action.
+  return next();
+};

package/server/register.js

@@ -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

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

@@ -0,0 +1,155 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs-extra');
+const _ = require('lodash');
+const { getAbsoluteServerUrl } = require('@strapi/utils');
+
+const { builApiEndpointPath } = require('../utils/builders');
+const defaultConfig = require('../config/default-config');
+
+module.exports = ({ strapi }) => {
+  const config = strapi.config.get('plugin.documentation');
+
+  return {
+    getDocumentationVersion() {
+      return _.get(config, 'info.version');
+    },
+
+    getFullDocumentationPath() {
+      return path.join(strapi.dirs.extensions, 'documentation', 'documentation');
+    },
+
+    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.extensions, api.name, 'documentation');
+      }
+
+      return path.join(strapi.dirs.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];
+    },
+
+    /**
+     * @description - Creates the Swagger json files
+     */
+    async generateFullDoc(version = this.getDocumentationVersion()) {
+      let paths = {};
+
+      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 apiPathsObject = builApiEndpointPath(api);
+
+        if (!apiPathsObject) {
+          continue;
+        }
+
+        await fs.ensureFile(apiDocPath);
+        await fs.writeJson(apiDocPath, apiPathsObject, { spaces: 2 });
+
+        paths = { ...paths, ...apiPathsObject.paths };
+      }
+
+      const fullDocJsonPath = path.join(
+        this.getFullDocumentationPath(),
+        version,
+        'full_documentation.json'
+      );
+
+      const settings = _.cloneDeep(defaultConfig);
+
+      const serverUrl = getAbsoluteServerUrl(strapi.config);
+      const apiPath = strapi.config.get('api.rest.prefix');
+
+      _.set(settings, 'servers', [
+        {
+          url: `${serverUrl}${apiPath}`,
+          description: 'Development server',
+        },
+      ]);
+
+      _.set(settings, ['info', 'x-generation-date'], new Date().toISOString());
+      _.set(settings, ['info', 'version'], version);
+
+      await fs.ensureFile(fullDocJsonPath);
+      await fs.writeJson(fullDocJsonPath, { ...settings, paths }, { spaces: 2 });
+    },
+  };
+};

package/server/services/index.js

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