@strapi/plugin-documentation 0.0.0-113ff29005

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2015-present Strapi Solutions SAS
+
+Portions of the Strapi software are licensed as follows:
+
+* All software that resides under an "ee/" directory (the “EE Software”), if that directory exists, is licensed under the license defined in "ee/LICENSE".
+
+* All software outside of the above-mentioned directories or restrictions above is available under the "MIT Expat" license as set forth below.
+
+MIT Expat License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# Plugin documentation
+
+This plugin automates your API documentation creation. It basically generates a swagger file. It follows the [Open API specification version 3.0.1](https://swagger.io/specification/).
+
+## Usage
+
+- Config
+- Creating a new documentation version
+- Generated files
+  - full_documentation.json structure
+- Overriding the suggested documentation
+- FAQ
+  - How does it generate the others plugins documentation ?
+  - I have created a route into a common API (like product) that query another model. How to automate this?
+- TODO
+
+### Config
+
+Create a `settings.json` file located in `src/extensions/documentation/config` folder where you can specify all your environment variables, licenses, external documentation and so one...
+You can add all the entries listed in the [specification](https://swagger.io/specification/).
+
+_NOTE_ if you need to add a custom key you can do it by prefixing your key by `x-{something}`
+
+### Creating a new documentation version
+
+In order to create a new version you need to change the `info.version` key in the `settings.json` file.
+
+This will automatically create a new version.
+
+### Generated files
+
+When you start your server with this plugin installed it will automatically create the following files in your APIs (we will see how it works for the plugins).
+
+- api
+  - my-api
+    - documentation
+      - documentationVersion // 1.0.0
+        - my-api.json // File containing all the identified path
+        - unclassified.json // File containing the manually added paths
+        - overrides // Folder to override the generated documentation
+- plugins
+  - ...
+  - documentation
+    - documentation
+      - 1.0.0
+        - full_documentation.json
+
+#### full_documentation.json
+
+The combined documentation is merged into the `full_documentation.json` file and it's located in `src/extensions/documentation/documentation/{version}/full_documentation.json`
+
+It has the following structure
+
+```
+{
+  "openapi": "3.0.0" // do not change this version
+  "info": {
+    "version": "1.0.0" // change this line to create a new version
+    ...
+  }
+  "x-strapi-config": {
+    "path": "/documentation", // Change this line to change to url of the doc
+    "showGeneratedFiles": true // Do not change this line at the moment...
+  },
+  "servers" {} // Your servers config (it will be automated),
+  "externalDocs": {},
+  "paths": {} // All your Api routes,
+  "tags": [] // Group of route
+  "components": {} // Default generated components and custom ones
+}
+```
+
+### Overriding the suggested documentation
+
+Currently the plugin writes a json file for each API.
+
+In order to customize the responses or to add information to a path you need to create a file in the associated `overrides/<file-name>.json` (the name of the file matters so make sure they are similar). Then you just need to identify the path you want to modify.
+You can modify the default generated tags by adding a new one at the end of the file. Same for the components.
+
+**_NOTE 1_**
+
+Overriding the `full_documentation.json` is a bad idea since it will be regenerated each time you change a model.
+
+**_NOTE 2_**
+
+You can modify the `tags`, `paths`, and `components` keys on the generated documentation by providing replacement values. You can see how the API is used in the users-permissions plugin: `packages/plugins/users-permissions/server/register.js`
+
+### FAQ
+
+#### How does it generate the others plugins documentation ?
+
+In other to reference a plugin's route into the documentation you need to add a `description` key in the `config` object.
+
+For example this is the plugin email routes.json file
+
+```
+{
+"routes": [
+  {
+    "method": "POST",
+    "path": "/",
+    "handler": "Email.send",
+    "config": {
+      "policies": [],
+      "description": "Send an email",
+      "tag": {
+        "plugin": "email",
+        "name": "Email"
+      }
+    }
+  },
+  {
+    "method": "GET",
+    "path": "/environments",
+    "handler": "Email.getEnvironments",
+    "config": {
+      "policies": []
+    }
+  },
+  {
+    "method": "GET",
+    "path": "/settings/:environment",
+    "handler": "Email.getSettings",
+    "config": {
+      "policies": []
+    }
+  },
+  {
+    "method": "PUT",
+    "path": "/settings/:environment",
+    "handler": "Email.updateSettings",
+    "config": {
+      "policies": []
+    }
+  }
+]
+}
+```
+
+In this file we have only one route that we want to reference in our documentation (`/`). Usually, the tag object is used for the SWAGGER UI, it will group this route under the `Email - Email` dropdown in the documentation. Furthermore, the algorithm will try to find the model to generate the best response possible. If the model is unknown it generates a response like the following `{ foo: "string" }` that you can easily override later.
+
+There's another property to guide the algorithm to create the best response possible, the `actionType` key.
+When we can't know by the controller name the type of the returned response (like `find` and `findOne`) you can specify it with this key. There's an example in `./plugins/users-permissions/config/routes.json`.
+
+#### I have created a route in a common API (like product) that query another model. How to automate this ?
+
+You can use the `tag` key in your route. If you provide a `tag` which is a string like `"tag": "Product"` the algorithm will know that the end-point retrieves data from the **`Product`** table. Creating a tag object `{ "tag": { "name": "User", "plugin": "User-Permissions } }` will result in generating a response with the **`User`** model from the plugin users-permissions.
+
+---
+
+Each entry of the object is easily customisable take look at the users-permissions ones they are a good example on how to do it.

package/__mocks__/strapi.js

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

@@ -0,0 +1,271 @@
+'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/components/FieldActionWrapper/index.js

@@ -0,0 +1,14 @@
+import styled from 'styled-components';
+import { FieldAction } from '@strapi/design-system/Field';
+
+const FieldActionWrapper = styled(FieldAction)`
+  svg {
+    height: 1rem;
+    width: 1rem;
+    path {
+      fill: ${({ theme }) => theme.colors.neutral600};
+    }
+  }
+`;
+
+export default FieldActionWrapper;

package/admin/src/components/PluginIcon/index.js

@@ -0,0 +1,12 @@
+/**
+ *
+ * PluginIcon
+ *
+ */
+
+import React from 'react';
+import Information from '@strapi/icons/Information';
+
+const PluginIcon = () => <Information />;
+
+export default PluginIcon;

package/admin/src/index.js

@@ -0,0 +1,80 @@
+// NOTE TO PLUGINS DEVELOPERS:
+// If you modify this file by adding new options to the plugin entry point
+// Here's the file: strapi/docs/3.0.0-beta.x/plugin-development/frontend-field-api.md
+// Here's the file: strapi/docs/3.0.0-beta.x/guides/registering-a-field-in-admin.md
+// Also the strapi-generate-plugins/files/admin/src/index.js needs to be updated
+// IF THE DOC IS NOT UPDATED THE PULL REQUEST WILL NOT BE MERGED
+import { prefixPluginTranslations } from '@strapi/helper-plugin';
+import pluginPkg from '../../package.json';
+import PluginIcon from './components/PluginIcon';
+import pluginPermissions from './permissions';
+import pluginId from './pluginId';
+
+const name = pluginPkg.strapi.name;
+
+export default {
+  register(app) {
+    app.addMenuLink({
+      to: `/plugins/${pluginId}`,
+      icon: PluginIcon,
+      intlLabel: {
+        id: `${pluginId}.plugin.name`,
+        defaultMessage: 'Documentation',
+      },
+      permissions: pluginPermissions.main,
+      async Component() {
+        const component = await import(
+          /* webpackChunkName: "documentation-page" */ './pages/PluginPage'
+        );
+
+        return component;
+      },
+    });
+
+    app.registerPlugin({
+      id: pluginId,
+      name,
+    });
+  },
+  bootstrap(app) {
+    app.addSettingsLink('global', {
+      intlLabel: {
+        id: `${pluginId}.plugin.name`,
+        defaultMessage: 'Documentation',
+      },
+      id: 'documentation',
+      to: `/settings/${pluginId}`,
+      async Component() {
+        const component = await import(
+          /* webpackChunkName: "documentation-settings" */ './pages/SettingsPage'
+        );
+
+        return component;
+      },
+      permissions: pluginPermissions.main,
+    });
+  },
+  async registerTrads({ locales }) {
+    const importedTrads = await Promise.all(
+      locales.map((locale) => {
+        return import(
+          /* webpackChunkName: "documentation-translation-[request]" */ `./translations/${locale}.json`
+        )
+          .then(({ default: data }) => {
+            return {
+              data: prefixPluginTranslations(data, pluginId),
+              locale,
+            };
+          })
+          .catch(() => {
+            return {
+              data: {},
+              locale,
+            };
+          });
+      })
+    );
+
+    return Promise.resolve(importedTrads);
+  },
+};