@akemona-org/strapi-plugin-documentation 3.7.0

package/admin/src/translations/zh-Hans.json

@@ -0,0 +1,31 @@
+{
+  "components.Row.generatedDate": "上一个生成的版本",
+  "components.Row.open": "打开",
+  "components.Row.regenerate": "重新生成",
+  "containers.HomePage.Block.title": "版本号",
+  "containers.HomePage.Button.open": "打开API文档",
+  "containers.HomePage.Button.update": "更新",
+  "containers.HomePage.PluginHeader.description": "配置API文档插件",
+  "containers.HomePage.PluginHeader.title": "API文档设置",
+  "containers.HomePage.PopUpWarning.confirm": "确定",
+  "containers.HomePage.PopUpWarning.message": "您确定要删除此版本吗？",
+  "containers.HomePage.copied": "令牌已被复制到粘贴板",
+  "containers.HomePage.form.jwtToken": "获取您的 JWT 令牌",
+  "containers.HomePage.form.jwtToken.description": "复制此令牌，并用它在 Swagger 中发出请求",
+  "containers.HomePage.form.password": "密码",
+  "containers.HomePage.form.password.inputDescription": "设置访问所需的密码",
+  "containers.HomePage.form.restrictedAccess": "限制访问",
+  "containers.HomePage.form.restrictedAccess.inputDescription": "将文档端点设为私有。默认情况下，访问是公开的。",
+  "containers.HomePage.form.showGeneratedFiles": "显示生成的文件",
+  "containers.HomePage.form.showGeneratedFiles.inputDescription": "当您想要覆盖生成的文档的时候很有用。 \n该插件将生成按型号和插件拆分的文件。 \n通过启用此选项，可以更轻松地自定义文档",
+  "error.deleteDoc.versionMissing": "您尝试删除的版本不存在。",
+  "error.noVersion": "需要一个版本",
+  "error.regenerateDoc": "重新生成文件时发生错误",
+  "error.regenerateDoc.versionMissing": "您尝试重新生成的版本不存在",
+  "notification.update.success": "设置更新成功",
+  "notification.delete.success": "API文档已删除",
+  "notification.generate.success": "API文档已生成",
+  "plugin.name": "OpenAPI文档",
+  "plugin.description.long": "创建一个 OpenAPI 文档，并通过 SWAGGER UI 直接查看。",
+  "plugin.description.short": "创建一个 OpenAPI 文档，并通过 SWAGGER UI 直接查看。"
+}

package/admin/src/translations/zh.json

@@ -0,0 +1,27 @@
+{
+  "components.Row.generatedDate": "最後產生的時間",
+  "components.Row.open": "開啟",
+  "components.Row.regenerate": "重新產生",
+  "containers.HomePage.Block.title": "版本",
+  "containers.HomePage.Button.open": "打開文件資料",
+  "containers.HomePage.Button.update": "更新",
+  "containers.HomePage.PluginHeader.description": "配置文件資料擴充套件設定",
+  "containers.HomePage.PluginHeader.title": "文件資料 - 設定",
+  "containers.HomePage.PopUpWarning.confirm": "我了解了",
+  "containers.HomePage.PopUpWarning.message": "你確定要刪除這個版本嗎？",
+  "containers.HomePage.copied": "Token 已經複製到剪貼簿",
+  "containers.HomePage.form.jwtToken": "存取你的 jwt token",
+  "containers.HomePage.form.jwtToken.description": "複製這個token並於swagger中使用於發出請求",
+  "containers.HomePage.form.password": "密碼",
+  "containers.HomePage.form.password.inputDescription": "設定密碼存取權限",
+  "containers.HomePage.form.restrictedAccess": "存取受到限制",
+  "containers.HomePage.form.restrictedAccess.inputDescription": "將endpoints設定為私密的. 預設是對外公開的",
+  "containers.HomePage.form.showGeneratedFiles": "顯示產生的檔案",
+  "containers.HomePage.form.showGeneratedFiles.inputDescription": "用於覆寫產生的文件檔案時. \n擴充套件會依照model及plugin分別產生檔案. \n啟用這個選項將會方便你客製化文件資料",
+  "error.deleteDoc.versionMissing": "你想刪除的版本不存在",
+  "error.noVersion": "版本是必填欄位",
+  "error.regenerateDoc": "重新產生文件資料時發生了錯誤",
+  "error.regenerateDoc.versionMissing": "你想產生的版本不存在",
+  "notification.update.success": "更新設定成功",
+  "plugin.name": "文件資料"
+}

package/admin/src/utils/getTrad.js

@@ -0,0 +1,5 @@
+import pluginId from '../pluginId';
+
+const getTrad = id => `${pluginId}.${id}`;
+
+export default getTrad;

package/admin/src/utils/openWithNewTab.js

@@ -0,0 +1,20 @@
+import { startsWith } from 'lodash';
+
+const openWithNewTab = path => {
+  const url = (() => {
+    if (startsWith(path, '/')) {
+      return `${strapi.backendURL}${path}`;
+    }
+    if (startsWith(path, 'https') || startsWith(path, 'http')) {
+      return path;
+    }
+
+    return `${strapi.backendURL}/${path}`;
+  })();
+
+  window.open(url, '_blank');
+
+  return window.focus();
+};
+
+export default openWithNewTab;

package/config/functions/bootstrap.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const _ = require('lodash');
+
+module.exports = async () => {
+  // Check if the plugin users-permissions is installed because the documentation needs it
+  if (Object.keys(strapi.plugins).indexOf('users-permissions') === -1) {
+    throw new Error(
+      'In order to make the documentation plugin works the users-permissions one is required'
+    );
+  }
+
+  const pluginStore = strapi.store({
+    environment: '',
+    type: 'plugin',
+    name: 'documentation',
+  });
+  const restrictedAccess = await pluginStore.get({ key: 'config' });
+
+  if (!restrictedAccess) {
+    pluginStore.set({ key: 'config', value: { restrictedAccess: false } });
+  }
+
+  let shouldUpdateFullDoc = false;
+  const services = strapi.plugins['documentation'].services.documentation;
+  // Generate plugins' documentation
+  const pluginsWithDocumentationNeeded = services.getPluginsWithDocumentationNeeded();
+  pluginsWithDocumentationNeeded.forEach(plugin => {
+    const isDocExisting = services.checkIfPluginDocumentationFolderExists(plugin);
+
+    if (!isDocExisting) {
+      services.createDocumentationDirectory(services.getPluginDocumentationPath(plugin));
+      // create the overrides directory
+      services.createDocumentationDirectory(services.getPluginOverrideDocumentationPath(plugin));
+      services.createPluginDocumentationFile(plugin);
+      shouldUpdateFullDoc = true;
+    } else {
+      const needToUpdatePluginDoc = services.checkIfPluginDocNeedsUpdate(plugin);
+
+      if (needToUpdatePluginDoc) {
+        services.createPluginDocumentationFile(plugin);
+        shouldUpdateFullDoc = true;
+      }
+    }
+  });
+
+  // Retrieve all the apis from the apis directory
+  const apis = services.getApis();
+  // Generate APIS' documentation
+  apis.forEach(api => {
+    const isDocExisting = services.checkIfDocumentationFolderExists(api);
+
+    if (!isDocExisting) {
+      // If the documentation directory doesn't exist create it
+      services.createDocumentationDirectory(services.getDocumentationPath(api));
+      // Create the overrides directory
+      services.createDocumentationDirectory(services.getDocumentationOverridesPath(api));
+      // Create the documentation files per version
+      services.createDocumentationFile(api); // Then create the {api}.json documentation file
+      shouldUpdateFullDoc = true;
+    } else {
+      const needToUpdateAPIDoc = services.checkIfAPIDocNeedsUpdate(api);
+
+      if (needToUpdateAPIDoc) {
+        services.createDocumentationFile(api);
+        shouldUpdateFullDoc = true;
+      }
+    }
+  });
+
+  const fullDoc = services.generateFullDoc();
+  // Verify that the correct documentation folder exists in the documentation plugin
+  const isMergedDocumentationExists = services.checkIfMergedDocumentationFolderExists();
+  const documentationPath = services.getMergedDocumentationPath();
+
+  if (isMergedDocumentationExists) {
+    /**
+     * Retrieve all tags from the documentation and join them
+     * @param {Object} documentation
+     * @returns {String}
+     */
+    const getDocTagsToString = documentation => {
+      return _.get(documentation, 'tags', [])
+        .map(tag => {
+          return tag.name.toLowerCase();
+        })
+        .sort((a, b) => a - b)
+        .join('.');
+    };
+    const oldDoc = require(path.resolve(documentationPath, 'full_documentation.json'));
+    const oldDocTags = getDocTagsToString(oldDoc);
+    const currentDocTags = getDocTagsToString(fullDoc);
+
+    // If the tags are different (an api has been deleted) we need to rebuild the documentation
+    if (oldDocTags !== currentDocTags) {
+      shouldUpdateFullDoc = true;
+    }
+  }
+
+  if (!isMergedDocumentationExists || shouldUpdateFullDoc) {
+    // Create the folder
+    services.createDocumentationDirectory(documentationPath);
+    // Write the file
+    fs.writeFileSync(
+      path.resolve(documentationPath, 'full_documentation.json'),
+      JSON.stringify(fullDoc, null, 2),
+      'utf8'
+    );
+  }
+
+  // Add permissions
+  const actions = [
+    {
+      section: 'plugins',
+      displayName: 'Access the Documentation',
+      uid: 'read',
+      pluginName: 'documentation',
+    },
+    {
+      section: 'plugins',
+      displayName: 'Update and delete',
+      uid: 'settings.update',
+      subCategory: 'settings',
+      pluginName: 'documentation',
+    },
+    {
+      section: 'plugins',
+      displayName: 'Regenerate',
+      uid: 'settings.regenerate',
+      subCategory: 'settings',
+      pluginName: 'documentation',
+    },
+  ];
+
+  await strapi.admin.services.permission.actionProvider.registerMany(actions);
+};

package/config/policies/index.js

@@ -0,0 +1,35 @@
+'use strict';
+
+module.exports = async (ctx, next) => {
+  const pluginStore = strapi.store({
+    environment: '',
+    type: 'plugin',
+    name: 'documentation',
+  });
+  const config = await pluginStore.get({ key: 'config' });
+
+  const redirectToLogin = () => {
+    const querystring = ctx.querystring ? `?${ctx.querystring}` : '';
+    ctx.redirect(
+      `${strapi.config.server.url}${strapi.plugins.documentation.config['x-strapi-config'].path}/login${querystring}`
+    );
+  };
+
+  if (!config.restrictedAccess) {
+    return await next();
+  }
+
+  if (!ctx.session.token) {
+    return redirectToLogin();
+  }
+
+  const isValid = await strapi.plugins['documentation'].services.token.validate(ctx.session.token);
+
+  if (!isValid) {
+    ctx.session.token = null;
+    return redirectToLogin();
+  }
+
+  // Execute the action.
+  await next();
+};

package/config/routes.json

@@ -0,0 +1,74 @@
+{
+  "routes": [
+    {
+      "method": "GET",
+      "path": "/",
+      "handler": "Documentation.index",
+      "config": {
+        "policies": [
+          "plugins::documentation.index",
+          ["admin::hasPermissions", ["plugins::documentation.read"]]
+        ]
+      }
+    },
+    {
+      "method": "GET",
+      "path": "/v:major(\\d+).:minor(\\d+).:patch(\\d+)",
+      "handler": "Documentation.index",
+      "config": {
+        "policies": [
+          "plugins::documentation.index",
+          ["admin::hasPermissions", ["plugins::documentation.read"]]
+        ]
+      }
+    },
+    {
+      "method": "GET",
+      "path": "/login",
+      "handler": "Documentation.loginView",
+      "config": {
+        "policies": [["admin::hasPermissions", ["plugins::documentation.read"]]]
+      }
+    },
+    {
+      "method": "POST",
+      "path": "/login",
+      "handler": "Documentation.login",
+      "config": {
+        "policies": [["admin::hasPermissions", ["plugins::documentation.read"]]]
+      }
+    },
+    {
+      "method": "GET",
+      "path": "/getInfos",
+      "handler": "Documentation.getInfos",
+      "config": {
+        "policies": [["admin::hasPermissions", ["plugins::documentation.read"]]]
+      }
+    },
+    {
+      "method": "POST",
+      "path": "/regenerateDoc",
+      "handler": "Documentation.regenerateDoc",
+      "config": {
+        "policies": [["admin::hasPermissions", ["plugins::documentation.settings.regenerate"]]]
+      }
+    },
+    {
+      "method": "PUT",
+      "path": "/updateSettings",
+      "handler": "Documentation.updateSettings",
+      "config": {
+        "policies": [["admin::hasPermissions", ["plugins::documentation.settings.update"]]]
+      }
+    },
+    {
+      "method": "DELETE",
+      "path": "/deleteDoc/:version",
+      "handler": "Documentation.deleteDoc",
+      "config": {
+        "policies": []
+      }
+    }
+  ]
+}

package/config/settings.json

@@ -0,0 +1,46 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "version": "1.0.0",
+    "title": "DOCUMENTATION",
+    "description": "",
+    "termsOfService": "YOUR_TERMS_OF_SERVICE_URL",
+    "contact": {
+      "name": "TEAM",
+      "email": "contact-email@something.io",
+      "url": "mywebsite.io"
+    },
+    "license": {
+      "name": "Apache 2.0",
+      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
+    }
+  },
+  "x-strapi-config": {
+    "path": "/documentation",
+    "showGeneratedFiles": true,
+    "generateDefaultResponse": true
+  },
+  "servers": [
+    {
+      "url": "http://localhost:1337",
+      "description": "Development server"
+    },
+    {
+      "url": "YOUR_STAGING_SERVER",
+      "description": "Staging server"
+    },
+    {
+      "url": "YOUR_PRODUCTION_SERVER",
+      "description": "Production server"
+    }
+  ],
+  "externalDocs": {
+    "description": "Find out more",
+    "url": "https://strapi.akemona.com/documentation/developer-docs/latest/getting-started/introduction.html"
+  },
+  "security": [
+    {
+      "bearerAuth": []
+    }
+  ]
+}

package/controllers/Documentation.js

@@ -0,0 +1,303 @@
+'use strict';
+
+/**
+ * Documentation.js controller
+ *
+ * @description: A set of functions called "actions" of the `documentation` plugin.
+ */
+
+// Core dependencies.
+const path = require('path');
+
+// Public dependencies.
+const fs = require('fs-extra');
+const cheerio = require('cheerio');
+const _ = require('lodash');
+const koaStatic = require('koa-static');
+
+module.exports = {
+  getInfos: async ctx => {
+    try {
+      const service = strapi.plugins.documentation.services.documentation;
+      const docVersions = service.retrieveDocumentationVersions();
+      const form = await service.retrieveFrontForm();
+
+      ctx.send({
+        docVersions,
+        currentVersion: service.getDocumentationVersion(),
+        prefix: strapi.plugins.documentation.config['x-strapi-config'].path,
+        form,
+      });
+    } 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.plugins.documentation.config.info.version;
+      const openAPISpecsPath = path.join(
+        strapi.config.appPath,
+        '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.config.appPath,
+            '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.config.appPath,
+              'extensions',
+              'documentation',
+              'public'
+            );
+            return await 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) {
+    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.plugins.documentation.config['x-strapi-config'].path}/login`,
+      });
+      const $ = cheerio.load(filledLayout);
+
+      $('.error').text(_.isEmpty(error) ? '' : 'Wrong password...');
+
+      try {
+        const layoutPath = path.resolve(
+          strapi.config.appPath,
+          '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.config.appPath,
+            'extensions',
+            'documentation',
+            'public'
+          );
+          return await 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: storedPassword } = await strapi
+      .store({
+        environment: '',
+        type: 'plugin',
+        name: 'documentation',
+        key: 'config',
+      })
+      .get();
+
+    const isValid = await strapi.plugins['users-permissions'].services.user.validatePassword(
+      password,
+      storedPassword
+    );
+    let querystring = '?error=password';
+
+    if (isValid) {
+      ctx.session.token = await strapi.plugins['documentation'].services.token.create();
+      querystring = '';
+    }
+
+    ctx.redirect(
+      `${strapi.config.server.url}${strapi.plugins.documentation.config['x-strapi-config'].path}${querystring}`
+    );
+  },
+
+  regenerateDoc: async ctx => {
+    const service = strapi.plugins.documentation.services.documentation;
+    const documentationVersions = service.retrieveDocumentationVersions().map(el => el.version);
+    const {
+      request: {
+        body: { version },
+        admin,
+      },
+    } = ctx;
+
+    if (_.isEmpty(version)) {
+      return ctx.badRequest(
+        null,
+        admin ? 'documentation.error.noVersion' : 'Please provide a version.'
+      );
+    }
+
+    if (!documentationVersions.includes(version)) {
+      return ctx.badRequest(
+        null,
+        admin
+          ? 'documentation.error.regenerateDoc.versionMissing'
+          : 'The version you are trying to generate does not exist.'
+      );
+    }
+
+    try {
+      strapi.reload.isWatching = false;
+      const fullDoc = service.generateFullDoc(version);
+      const documentationPath = service.getMergedDocumentationPath(version);
+      // Write the file
+      fs.writeFileSync(
+        path.resolve(documentationPath, 'full_documentation.json'),
+        JSON.stringify(fullDoc, null, 2),
+        'utf8'
+      );
+      ctx.send({ ok: true });
+    } catch (err) {
+      ctx.badRequest(null, admin ? 'documentation.error.regenerateDoc' : 'An error occured');
+    } finally {
+      strapi.reload.isWatching = true;
+    }
+  },
+
+  deleteDoc: async ctx => {
+    strapi.reload.isWatching = false;
+    const service = strapi.plugins.documentation.services.documentation;
+    const documentationVersions = service.retrieveDocumentationVersions().map(el => el.version);
+    const {
+      request: {
+        params: { version },
+        admin,
+      },
+    } = ctx;
+
+    if (_.isEmpty(version)) {
+      return ctx.badRequest(
+        null,
+        admin ? 'documentation.error.noVersion' : 'Please provide a version.'
+      );
+    }
+
+    if (!documentationVersions.includes(version)) {
+      return ctx.badRequest(
+        null,
+        admin
+          ? 'documentation.error.deleteDoc.versionMissing'
+          : 'The version you are trying to delete does not exist.'
+      );
+    }
+
+    try {
+      await service.deleteDocumentation(version);
+      ctx.send({ ok: true });
+    } catch (err) {
+      ctx.badRequest(null, admin ? 'notification.error' : err.message);
+    } finally {
+      strapi.reload.isWatching = true;
+    }
+  },
+
+  updateSettings: async ctx => {
+    const {
+      admin,
+      body: { restrictedAccess, password },
+    } = ctx.request;
+    const usersPermService = strapi.plugins['users-permissions'].services;
+    const pluginStore = strapi.store({
+      environment: '',
+      type: 'plugin',
+      name: 'documentation',
+    });
+    const prevConfig = await pluginStore.get({ key: 'config' });
+
+    if (restrictedAccess && _.isEmpty(password)) {
+      return ctx.badRequest(
+        null,
+        admin ? 'users-permissions.Auth.form.error.password.provide' : 'Please provide a password'
+      );
+    }
+
+    const isNewPassword = !_.isEmpty(password) && password !== prevConfig.password;
+
+    if (isNewPassword && usersPermService.user.isHashed(password)) {
+      // Throw an error if the password selected by the user
+      // contains more than two times the symbol '$'.
+      return ctx.badRequest(
+        null,
+        admin
+          ? 'users-permissions.Auth.form.error.password.format'
+          : 'our password cannot contain more than three times the symbol `$`.'
+      );
+    }
+
+    if (isNewPassword) {
+      prevConfig.password = await usersPermService.user.hashPassword({
+        password,
+      });
+    }
+
+    _.set(prevConfig, 'restrictedAccess', restrictedAccess);
+
+    await pluginStore.set({ key: 'config', value: prevConfig });
+
+    return ctx.send({ ok: true });
+  },
+};

package/middlewares/documentation/defaults.json

@@ -0,0 +1,5 @@
+{
+  "documentation": {
+    "enabled": true
+  }
+}