@strapi/plugin-documentation 4.10.0-beta.1 → 4.10.1-experimental.0

package/server/services/override.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const { getPluginsThatNeedDocumentation } = require('./utils/get-plugins-that-need-documentation');
+
+module.exports = ({ strapi }) => {
+  const registeredOverrides = [];
+  const excludedFromGeneration = [];
+
+  return {
+    registeredOverrides,
+    excludedFromGeneration,
+    /**
+     *
+     * @param {(string | string[])} api - The name of the api or and array of apis to exclude from generation
+     */
+    excludeFromGeneration(api) {
+      if (Array.isArray(api)) {
+        excludedFromGeneration.push(...api);
+
+        return;
+      }
+
+      excludedFromGeneration.push(api);
+    },
+    /**
+     * @TODO pluginOrigin should be required in next major release
+     * @param {object} doc - The openapi specifcation to override
+     * @param {object} options - The options to override the documentation
+     * @param {(string | undefined)} options.pluginOrigin - The name of the plugin that is overriding the documentation
+     * @param {string[]} options.excludeFromGeneration - The list of apis or plugins to exclude from generation
+     */
+    registerOverride(override, { pluginOrigin, excludeFromGeneration = [] } = {}) {
+      const pluginsThatNeedDocumentation = getPluginsThatNeedDocumentation(
+        strapi.config.get('plugin.documentation')
+      );
+      // Don't apply the override if the plugin is not in the list of plugins that need documentation
+      if (pluginOrigin && !pluginsThatNeedDocumentation.includes(pluginOrigin)) return;
+
+      if (excludeFromGeneration.length) {
+        this.excludeFromGeneration(excludeFromGeneration);
+      }
+
+      let overrideToRegister = override;
+      // Parse yaml if we receive a string
+      if (typeof override === 'string') {
+        overrideToRegister = require('yaml').parse(overrideToRegister);
+      }
+      // receive an object we can register it directly
+      registeredOverrides.push(overrideToRegister);
+    },
+  };
+};

package/server/services/utils/default-openapi-components.js

@@ -0,0 +1,40 @@
+'use strict';
+
+module.exports = {
+  securitySchemes: {
+    bearerAuth: {
+      type: 'http',
+      scheme: 'bearer',
+      bearerFormat: 'JWT',
+    },
+  },
+  schemas: {
+    Error: {
+      type: 'object',
+      required: ['error'],
+      properties: {
+        data: {
+          nullable: true,
+          oneOf: [{ type: 'object' }, { type: 'array', items: { type: 'object' } }],
+        },
+        error: {
+          type: 'object',
+          properties: {
+            status: {
+              type: 'integer',
+            },
+            name: {
+              type: 'string',
+            },
+            message: {
+              type: 'string',
+            },
+            details: {
+              type: 'object',
+            },
+          },
+        },
+      },
+    },
+  },
+};

package/server/services/utils/get-plugins-that-need-documentation.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const getPluginsThatNeedDocumentation = (config) => {
+  // Default plugins that need documentation generated
+  const defaultPlugins = ['upload', 'users-permissions'];
+
+  // User specified plugins that need documentation generated
+  const userPluginsConfig = config['x-strapi-config'].plugins;
+
+  if (userPluginsConfig === null) {
+    // The user hasn't specified any plugins to document, use the defaults
+    return defaultPlugins;
+  }
+
+  if (userPluginsConfig.length) {
+    // The user has specified certain plugins to document, use them
+    return userPluginsConfig;
+  }
+
+  // The user has specified that no plugins should be documented
+  return [];
+};
+
+module.exports = { getPluginsThatNeedDocumentation };

package/__mocks__/strapi.js

@@ -1,41 +0,0 @@
-'use strict';
-
-const strapi = {
-  plugins: {
-    'users-permissions': {
-      contentTypes: {
-        role: {
-          attributes: {
-            name: {
-              type: 'string',
-            },
-          },
-        },
-      },
-      routes: {
-        'content-api': {
-          routes: [],
-        },
-      },
-    },
-  },
-  api: {
-    restaurant: {
-      contentTypes: {
-        restaurant: {
-          attributes: {
-            name: {
-              type: 'string',
-            },
-          },
-        },
-      },
-      routes: {
-        restaurant: { routes: [] },
-      },
-    },
-  },
-  contentType: () => ({ info: {}, attributes: { test: { type: 'string' } } }),
-};
-
-module.exports = strapi;

package/__tests__/build-component-schema.test.js

@@ -1,271 +0,0 @@
-'use strict';
-
-const _ = require('lodash');
-const buildComponentSchema = require('../server/services/helpers/build-component-schema');
-const strapi = require('../__mocks__/strapi');
-
-describe('Build Component Schema', () => {
-  beforeEach(() => {
-    // Reset the mocked strapi instance
-    global.strapi = _.cloneDeep(strapi);
-  });
-
-  it('builds the Response schema', () => {
-    const apiMocks = [
-      {
-        name: 'users-permissions',
-        getter: 'plugin',
-        ctNames: ['role'],
-      },
-      { name: 'restaurant', getter: 'api', ctNames: ['restaurant'] },
-    ];
-
-    let schemas = {};
-    for (const mock of apiMocks) {
-      schemas = {
-        ...schemas,
-        ...buildComponentSchema(mock),
-      };
-    }
-
-    const schemaNames = Object.keys(schemas);
-    const [pluginResponseName, apiResponseName] = Object.keys(schemas);
-    const [pluginResponseValue, apiResponseValue] = Object.values(schemas);
-
-    const expectedShape = {
-      type: 'object',
-      properties: {
-        data: {
-          type: 'object',
-          properties: {
-            id: { type: 'string' },
-            attributes: { type: 'object', properties: { test: { type: 'string' } } },
-          },
-        },
-        meta: { type: 'object' },
-      },
-    };
-
-    expect(schemaNames.length).toBe(2);
-    expect(pluginResponseName).toBe('UsersPermissionsRoleResponse');
-    expect(apiResponseName).toBe('RestaurantResponse');
-    expect(pluginResponseValue).toStrictEqual(expectedShape);
-    expect(apiResponseValue).toStrictEqual(expectedShape);
-  });
-
-  it('builds the ResponseList schema', () => {
-    global.strapi.plugins['users-permissions'].routes['content-api'].routes = [
-      { method: 'GET', path: '/test', handler: 'test.find' },
-    ];
-    global.strapi.api.restaurant.routes.restaurant.routes = [
-      { method: 'GET', path: '/test', handler: 'test.find' },
-    ];
-
-    const apiMocks = [
-      {
-        name: 'users-permissions',
-        getter: 'plugin',
-        ctNames: ['role'],
-      },
-      { name: 'restaurant', getter: 'api', ctNames: ['restaurant'] },
-    ];
-
-    let schemas = {};
-    for (const mock of apiMocks) {
-      schemas = {
-        ...schemas,
-        ...buildComponentSchema(mock),
-      };
-    }
-
-    const schemaNames = Object.keys(schemas);
-    const pluginListResponseValue = schemas.UsersPermissionsRoleListResponse;
-    const apiListResponseValue = schemas.RestaurantListResponse;
-
-    const expectedShape = {
-      type: 'object',
-      properties: {
-        data: {
-          type: 'array',
-          items: {
-            type: 'object',
-            properties: {
-              id: { type: 'string' },
-              attributes: { type: 'object', properties: { test: { type: 'string' } } },
-            },
-          },
-        },
-        meta: {
-          type: 'object',
-          properties: {
-            pagination: {
-              properties: {
-                page: { type: 'integer' },
-                pageSize: { type: 'integer', minimum: 25 },
-                pageCount: { type: 'integer', maximum: 1 },
-                total: { type: 'integer' },
-              },
-            },
-          },
-        },
-      },
-    };
-
-    expect(schemaNames.length).toBe(4);
-    expect(schemaNames.includes('UsersPermissionsRoleListResponse')).toBe(true);
-    expect(schemaNames.includes('RestaurantListResponse')).toBe(true);
-    expect(pluginListResponseValue).toStrictEqual(expectedShape);
-    expect(apiListResponseValue).toStrictEqual(expectedShape);
-  });
-
-  it('builds the Request schema', () => {
-    global.strapi.plugins['users-permissions'].routes['content-api'].routes = [
-      { method: 'POST', path: '/test', handler: 'test.create' },
-    ];
-    global.strapi.api.restaurant.routes.restaurant.routes = [
-      { method: 'POST', path: '/test', handler: 'test.create' },
-    ];
-
-    const apiMocks = [
-      {
-        name: 'users-permissions',
-        getter: 'plugin',
-        ctNames: ['role'],
-      },
-      { name: 'restaurant', getter: 'api', ctNames: ['restaurant'] },
-    ];
-
-    let schemas = {};
-    for (const mock of apiMocks) {
-      schemas = {
-        ...schemas,
-        ...buildComponentSchema(mock),
-      };
-    }
-
-    const schemaNames = Object.keys(schemas);
-    const pluginListResponseValue = schemas.UsersPermissionsRoleRequest;
-    const apiListResponseValue = schemas.RestaurantRequest;
-
-    const expectedShape = {
-      type: 'object',
-      required: ['data'],
-      properties: {
-        data: {
-          required: [],
-          type: 'object',
-          properties: { test: { type: 'string' } },
-        },
-      },
-    };
-
-    expect(schemaNames.length).toBe(4);
-    expect(schemaNames.includes('UsersPermissionsRoleRequest')).toBe(true);
-    expect(schemaNames.includes('RestaurantRequest')).toBe(true);
-    expect(pluginListResponseValue).toStrictEqual(expectedShape);
-    expect(apiListResponseValue).toStrictEqual(expectedShape);
-  });
-
-  it('builds the LocalizationResponse schema', () => {
-    global.strapi.plugins['users-permissions'].routes['content-api'].routes = [
-      { method: 'GET', path: '/localizations', handler: 'test' },
-    ];
-    global.strapi.api.restaurant.routes.restaurant.routes = [
-      { method: 'GET', path: '/localizations', handler: 'test' },
-    ];
-
-    const apiMocks = [
-      {
-        name: 'users-permissions',
-        getter: 'plugin',
-        ctNames: ['role'],
-      },
-      { name: 'restaurant', getter: 'api', ctNames: ['restaurant'] },
-    ];
-
-    let schemas = {};
-    for (const mock of apiMocks) {
-      schemas = {
-        ...schemas,
-        ...buildComponentSchema(mock),
-      };
-    }
-
-    const schemaNames = Object.keys(schemas);
-    const pluginListResponseValue = schemas.UsersPermissionsRoleLocalizationResponse;
-    const apiListResponseValue = schemas.RestaurantLocalizationResponse;
-
-    const expectedShape = {
-      type: 'object',
-      properties: {
-        id: { type: 'string' },
-        test: { type: 'string' },
-      },
-    };
-
-    expect(schemaNames.length).toBe(4);
-    expect(schemaNames.includes('UsersPermissionsRoleLocalizationResponse')).toBe(true);
-    expect(schemaNames.includes('RestaurantLocalizationResponse')).toBe(true);
-    expect(pluginListResponseValue).toStrictEqual(expectedShape);
-    expect(apiListResponseValue).toStrictEqual(expectedShape);
-  });
-
-  it('builds the LocalizationRequest schema', () => {
-    global.strapi.plugins['users-permissions'].routes['content-api'].routes = [
-      { method: 'POST', path: '/localizations', handler: 'test' },
-    ];
-    global.strapi.api.restaurant.routes.restaurant.routes = [
-      { method: 'POST', path: '/localizations', handler: 'test' },
-    ];
-
-    const apiMocks = [
-      {
-        name: 'users-permissions',
-        getter: 'plugin',
-        ctNames: ['role'],
-      },
-      { name: 'restaurant', getter: 'api', ctNames: ['restaurant'] },
-    ];
-
-    let schemas = {};
-    for (const mock of apiMocks) {
-      schemas = {
-        ...schemas,
-        ...buildComponentSchema(mock),
-      };
-    }
-
-    const schemaNames = Object.keys(schemas);
-    const pluginListResponseValue = schemas.UsersPermissionsRoleLocalizationRequest;
-    const apiListResponseValue = schemas.RestaurantLocalizationRequest;
-
-    const expectedShape = {
-      type: 'object',
-      required: ['locale'],
-      properties: { test: { type: 'string' } },
-    };
-
-    expect(schemaNames.length).toBe(8);
-    expect(schemaNames.includes('UsersPermissionsRoleLocalizationRequest')).toBe(true);
-    expect(schemaNames.includes('RestaurantLocalizationRequest')).toBe(true);
-    expect(pluginListResponseValue).toStrictEqual(expectedShape);
-    expect(apiListResponseValue).toStrictEqual(expectedShape);
-  });
-
-  it('creates the correct name given multiple content types', () => {
-    const apiMock = {
-      name: 'users-permissions',
-      getter: 'plugin',
-      ctNames: ['permission', 'role', 'user'],
-    };
-
-    const schemas = buildComponentSchema(apiMock);
-    const schemaNames = Object.keys(schemas);
-    const [permission, role, user] = schemaNames;
-
-    expect(schemaNames.length).toBe(3);
-    expect(permission).toBe('UsersPermissionsPermissionResponse');
-    expect(role).toBe('UsersPermissionsRoleResponse');
-    expect(user).toBe('UsersPermissionsUserResponse');
-  });
-});

package/admin/src/pages/utils/api.js

@@ -1,31 +0,0 @@
-import { request } from '@strapi/helper-plugin';
-import pluginId from '../../pluginId';
-
-const deleteDoc = ({ prefix, version }) => {
-  return request(`${prefix}/deleteDoc/${version}`, { method: 'DELETE' });
-};
-
-const fetchDocumentationVersions = async (toggleNotification) => {
-  try {
-    const data = await request(`/${pluginId}/getInfos`, { method: 'GET' });
-
-    return data;
-  } catch (err) {
-    toggleNotification({
-      type: 'warning',
-      message: { id: 'notification.error' },
-    });
-
-    // FIXME
-    return null;
-  }
-};
-
-const regenerateDoc = ({ prefix, version }) => {
-  return request(`${prefix}/regenerateDoc`, { method: 'POST', body: { version } });
-};
-
-const updateSettings = ({ prefix, body }) =>
-  request(`${prefix}/updateSettings`, { method: 'PUT', body });
-
-export { deleteDoc, fetchDocumentationVersions, regenerateDoc, updateSettings };