Make plugins documentation generation optional (#5465)

* Make plugins documentation generation optional

Signed-off-by: Ralph Maroun <rmaroun@outlook.com>

* Removing "-" character from schema names for generated plugin documentation so it becomes compatible with AWS API gateway import API feature using OAS file. Adding only one property to the settings file pluginsForWhichToGenerateDoc so that the user can choose for which plugin he wishes to generate documentation. Adding a parameter to generate or not the default response (this can now be set to false to have a documentation that is compatible with AWS API Gateway).

Signed-off-by: Ralph Maroun <rmaroun@outlook.com>

* Updating settings.json to start without the pluginsForWhichToGenerateDoc key so that all plugins documentation gets generated by default. Updated the documentation to reflect this change.

Signed-off-by: Ralph Maroun <rmaroun@outlook.com>

* Updating documentation to correct typos and rephrase some sentences to make them more clear.

Signed-off-by: Ralph Maroun <rmaroun@outlook.com>

* Destructuring the config to the var pluginsForWhichToGenerateDoc instead of renaming it to take into account comment from Alexandre Bodin

Signed-off-by: Ralph Maroun <rmaroun@outlook.com>

* Destructuring generateDefaultResponse and pluginsForWhichToGenerateDoc from strapi config object based on feedback from Alexandre Bodin

Signed-off-by: Ralph Maroun <rmaroun@outlook.com>

Co-authored-by: Alexandre BODIN <alexandrebodin@users.noreply.github.com>

docs/3.0.0-beta.x/plugins/documentation.md

@@ -101,7 +101,12 @@ Here are the file that needs to be created in order to change the documentation
   },
   "x-strapi-config": {
     "path": "/documentation",
-    "showGeneratedFiles": true
+    "showGeneratedFiles": true",
+    "pluginsForWhichToGenerateDoc": [
+      "email",
+      "upload",
+      "users-permissions"
+    ]
   },
   "servers": [
     {
@@ -171,6 +176,59 @@ To access your documentation on a custom path, you will have to update the `path
 }
 ```
 
+### Indicate which plugins' documentation to generate
+
+To generate documentation for specific plugins, you will need to indicate the list of all the plugins for which you wish to generate documentation. In order to do that you need to update the `pluginsForWhichToGenerateDoc` key. Leaving this key with an empty array `[]` means that not any plugin documentation will be generated. If you wish to generate documentation for all plugins, you just have to remove the key from the `settings.json` file.
+
+```
+{
+  "x-strapi-config": {
+    "pluginsForWhichToGenerateDoc": [
+      "email",
+      "upload",
+      "users-permissions"
+    ],
+  }
+}
+```
+
+In the previous example, you will generate documentation for the upload, email and users permissions (permissions and roles) plugins.
+
+### Default Response
+
+Sometimes, an operation can return multiple errors with different HTTP status codes, but all of them have the same response structure. You can use the default response to describe these errors collectively, not individually. “Default” means this response is used for all HTTP codes that are not covered individually for this operation.
+
+This is how it would looks like
+
+```
+responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+        # Definition of all error statuses
+        default:
+          description: Unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+```
+
+You can set the generation of the default response with the following attribute `generateDefaultResponse`
+
+```
+{
+  "x-strapi-config": {
+    "generateDefaultResponse": true
+  }
+}
+```
+
+Note: this is configurable as some API Gateways does not support a default response.
+
 ## File structure
 
 This plugin follows the OpenApi Specifications ([0AS.3.0.2](https://swagger.io/specification/)) and generates an OpenAPI Document called `full_documentation.json`.

packages/strapi-plugin-documentation/config/functions/bootstrap.js

@@ -90,19 +90,10 @@ module.exports = async () => {
      * @returns {String}
      */
     const getDocTagsToString = documentation => {
-      const defaultGeneratedTags = [
-        'email',
-        'upload - file',
-        'users-permissions - role',
-        'authentication',
-        'users-permissions - user',
-      ];
-
       return _.get(documentation, 'tags', [])
         .map(tag => {
           return tag.name.toLowerCase();
         })
-        .filter(tag => defaultGeneratedTags.indexOf(tag) === -1)
         .sort((a, b) => a - b)
         .join('.');
     };

packages/strapi-plugin-documentation/config/settings.json

@@ -17,7 +17,8 @@
   },
   "x-strapi-config": {
     "path": "/documentation",
-    "showGeneratedFiles": true
+    "showGeneratedFiles": true,
+    "generateDefaultResponse": true
   },
   "servers": [
     {

packages/strapi-plugin-documentation/services/Documentation.js

@@ -366,8 +366,8 @@ module.exports = {
     const formattedPluginName = plugin
       .split('-')
       .map(i => _.upperFirst(i))
-      .join('-');
-    const formattedName = _.upperFirst(name);
+      .join('');
+    const formattedName = _.upperFirst(name); 
 
     if (withoutSpace) {
       return `${formattedPluginName}${formattedName}`;
@@ -950,7 +950,7 @@ module.exports = {
       schema = this.generatePluginResponseSchema(tag);
     }
 
-    return {
+    const response = {
       200: {
         description: 'response',
         content: {
@@ -979,17 +979,24 @@ module.exports = {
           },
         },
       },
-      default: {
-        description: 'unexpected error',
-        content: {
-          'application/json': {
-            schema: {
-              $ref: '#/components/schemas/Error',
-            },
-          },
-        },
-      },
     };
+
+    const { generateDefaultResponse } = strapi.plugins.documentation.config['x-strapi-config'];
+
+    if (generateDefaultResponse) {
+      response.default = {
+          description: 'unexpected error',
+          content: {
+            'application/json': {
+              schema: {
+                $ref: '#/components/schemas/Error',
+              },
+            },
+          }
+        }
+    }
+
+    return response;
   },
 
   /**
@@ -1009,7 +1016,7 @@ module.exports = {
       endPoint
     );
 
-    return {
+    const response = {
       200: {
         description,
         content: {
@@ -1038,17 +1045,24 @@ module.exports = {
           },
         },
       },
-      default: {
-        description: 'unexpected error',
-        content: {
-          'application/json': {
-            schema: {
-              $ref: '#/components/schemas/Error',
-            },
-          },
-        },
-      },
     };
+
+    const { generateDefaultResponse } = strapi.plugins.documentation.config['x-strapi-config'];
+
+    if (generateDefaultResponse) {
+      response.default = {
+          description: 'unexpected error',
+          content: {
+            'application/json': {
+              schema: {
+                $ref: '#/components/schemas/Error',
+              },
+            },
+          }
+        }
+    }
+
+    return response;
   },
 
   /**
@@ -1770,11 +1784,12 @@ module.exports = {
    * @returns {Boolean}
    */
   isPluginDocumentationNeeded: function(pluginName) {
-    const pluginRoutesWithDescription = this.getPluginRoutesWithDescription(
-      pluginName
-    );
-
-    return pluginRoutesWithDescription.length > 0;
+    const { pluginsForWhichToGenerateDoc } = strapi.plugins.documentation.config['x-strapi-config'];
+    if (Array.isArray(pluginsForWhichToGenerateDoc) && !pluginsForWhichToGenerateDoc.includes(pluginName)) {
+        return false;
+    } else {
+        return this.getPluginRoutesWithDescription(pluginName).length > 0;
+    }
   },
 
   /**