'pluginsForWhichToGenerateDoc' property not taking effect on API Documentation plugin

[rsandgarten]

'pluginsForWhichToGenerateDoc' property not taking effect on API Documentation plugin

Required System information

• Node.js version: 16.15.1
• YARN version: 1.22.19
• NPM version: 7.24.2 (however, I'm using yarn as package manager)
• Strapi version: 4.2.3
• Database: SQLite ( but also reproducible with Postgres)
• Operating system: Windows 10

Describe the bug

I'm trying to hide the user-permissions plugin set of endpoints from the generated API Documentation (openapi/swagger). Even though the pluginsForWhichToGenerateDoc attribute is meant to be used to select which plugins are included/ignored, no matter if I remove the user-permissions value item, or even leave the array empty, still, all plugin endpoints are generated in the OpenAPI docs.

Steps to reproduce the behavior

1. yarn create strapi-app my-project --quickstart
2. cd my-project
3. yarn strapi install documentation
4. yarn develop --> at this point de default openapi docs are generated
5. add settings.json file on .\extensions\documentation\config as described here, but remove the users-permissions item from pluginsForWhichToGenerateDoc array (or leave an empty array [ ]).
6. Regenerate docs through the Documentation plugin UI
7. Open docs and see the user permissions endpoints are still included in the docs

Expected behavior

The User Permissions plugin set of endpoints not to be included in the OpenApi docs.

Screenshots

Here you can see how the User Permission set of endpoints are still present on the OpenApi documentation (as well as the File Upload). And it also confirms that the settings.json file is properly created, since the Title is updated with a custom value ("MY CUSTOM DOCUMENTATION").

Code snippets

Here is the complete settings.json file (note the pluginsForWhichToGenerateDoc is an empty array):

{
    "openapi": "3.0.0",
    "info": {
      "version": "1.0.0",
      "title": "MY CUSTOM DOCUMENTATION",
      "description": "",
      "termsOfService": "https://some-tos-url.com",
      "contact": {
        "name": "TEAM",
        "email": "[email protected]",
        "url": "https://some-custom-url.com"
      },
      "license": {
        "name": "Apache 2.0",
        "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
      }
    },
    "x-strapi-config": {
      "path": "/documentation",
      "showGeneratedFiles": true,
      "pluginsForWhichToGenerateDoc": [
      ]
    },
    "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.io/documentation/"
    },
    "security": [
      {
        "bearerAuth": []
      }
    ],
    "paths": {},
    "tags": [],
    "components": {}
  }

Additional context

I even tried re-building the strapi app, stopped, re started, etc. I suspect this might be related to this fix #12555 (now the problem seems to be reverted).

Currently, this is a big deal for me since I have a NextJS client app, that uses openapi-generator-cli to generate the the client code, but unfortunately, it's failing due to a couple of the User Permissions endpoints. So, as a work-around, I'm trying to hide them. This additional context might popup as a separate issue (not yet sure if I should post it on openapi-generator-cli or strapi repo).

[miroslavzeman]

I'm facing same issue. I'm trying to generate open api using openapi-typescript-codegen and the user-permissions generated code is just broken. I'm also trying to figure out how to exclude users-permission from swagger to "solve" the issue, but I'm not having any success.

[koli2]

@miro4994 As a workaround I exluded it with own nodejs script.

I loaded original json file. Removed these keys below and then saved.

['paths']['/auth/send-email-confirmation']
['paths']['/auth/send-email-confirmation']
['paths']['/users-permissions/roles']
['paths']['/users-permissions/roles/{role}']
['paths']['/auth/forgot-password']
['paths']['/auth/send-email-confirmation']
['paths']['/connect/(.*)']

[christian-reichart]

@koli2 Thanks for your workaround, can you post your complete node script? trying to implement this for now and am not sure how I can easily exclude those keys.

[koli2]

@christian-reichart Of course.

const fs = require('fs');

const main = async () => {
  try {
    const data = fs
      .readFileSync('./src/api/full_documentation.json', 'utf8')
      .replace(/datetime/g, 'string');
    const parsed = JSON.parse(data);
    delete parsed['paths']['/auth/send-email-confirmation'];
    delete parsed['paths']['/auth/send-email-confirmation'];
    delete parsed['paths']['/users-permissions/roles'];
    delete parsed['paths']['/users-permissions/roles/{role}'];
    delete parsed['paths']['/auth/forgot-password'];
    delete parsed['paths']['/auth/send-email-confirmation'];
    delete parsed['paths']['/connect/(.*)'];
    fs.writeFileSync(
      './src/api/full_documentation_clean.json',
      JSON.stringify(parsed)
    );
  } catch (err) {
    console.log(err);
  }
};

main();

Run with node ./scripts/yourFilename.js

[christian-reichart]

@koli2 much appreciated, thank you! :)

[rsandgarten]

Thanks for sharing that @koli2 I moved forward with your suggestion. In my case, I had to remove other endpoints as well until the doc was generated without errors:

delete parsed['paths']['/connect/(.*)'];
delete parsed['paths']['/auth/local'];
delete parsed['paths']['/auth/local/register'];
delete parsed['paths']['/auth/{provider}/callback'];
delete parsed['paths']['/auth/forgot-password'];
delete parsed['paths']['/auth/reset-password'];
delete parsed['paths']['/auth/email-confirmation'];
delete parsed['paths']['/auth/send-email-confirmation'];
delete parsed['paths']['/users-permissions/permissions'];
delete parsed['paths']['/users-permissions/roles/{id}'];
delete parsed['paths']['/users-permissions/roles'];
delete parsed['paths']['/users-permissions/roles/{role}'];
delete parsed['paths']['/users/count'];
delete parsed['paths']['/users'];
delete parsed['paths']['/users/me'];
delete parsed['paths']['/users/{id}'];

Of course, I'm still interested to know if the strapi team would attempt a fix on this issue, as well as #13885