[Request]: Documentation plugin fails to auto-detect custom fields in users-permissions register endpoint

[murschiid]

Summary

The Strapi documentation plugin does not automatically detect custom fields added to the users-permissions User content-type, forcing developers to use redundant manual overrides.

Why is it needed?

I'm always frustrated when I properly extend the User content-type with custom fields and configure the users-permissions plugin, but the documentation completely ignores these fields. This creates a broken developer experience where:

API works - custom fields are accepted in actual requests

Documentation lies - Swagger UI shows incomplete/inaccurate API specs

Forces workarounds - developers must manually override documentation with mutateDocumentation

Maintenance nightmare - fields are defined in multiple places (schema + documentation override)

This defeats the purpose of having auto-generated documentation and creates inconsistency between the actual API behavior and its documentation.

Suggested solution(s)

The documentation plugin should automatically detect and include custom fields from:

User content-type schema extensions (src/extensions/users-permissions/content-types/user/schema.json)

users-permissions plugin configuration (allowedFields in plugin config)

Expected behavior:

When I add firstName and lastName to User schema as required fields

And configure allowedFields: ['firstName', 'lastName']

The /auth/local/register endpoint documentation should automatically show all 5 required fields (username, email, password, firstName, lastName)

Current broken behavior:

Only shows default fields (username, email, password)

Forces manual documentation overrides

The fix should ensure that any fields properly configured for registration automatically appear in the generated OpenAPI documentation without manual intervention.

Related issue(s)/PR(s)

No response

[github-actions]

🤖 I've analyzed your question and here's what I found:

Thanks a lot for taking the time to write such a clear report and for explaining the impact on your workflow — this is really valuable feedback for us and for other developers hitting the same problem.

From the available docs, there are a few important points about how these pieces work today:

1. Users & Permissions registration fields

   In Strapi 5, any additional fields you want to accept on the /auth/local/register endpoint must be explicitly listed in the Users & Permissions plugin configuration under register.allowedFields. [Register fields; Breaking change]

   Example:

   // config/plugins.js
   module.exports = ({ env }) => ({
     // ...
     'users-permissions': {
       config: {
         register: {
           allowedFields: ['firstName', 'lastName'],
         },
       },
     },
     // ...
   });

   And your extra user attributes live in the extended User schema under src/extensions/users-permissions/content-types/user/schema.json. [Plugin extensions]

2. Documentation plugin vs. OpenAPI generator

   • The Documentation plugin (@strapi/plugin-documentation) scans content-types and routes and generates an OpenAPI/Swagger file, then serves it via Swagger UI in the admin. [Documentation plugin]
   • This plugin is currently marked as “Unmaintained plugin – may not work with Strapi 5”, so its behavior with newer Strapi 5 features (like the stricter register.allowedFields) is not guaranteed. [Documentation plugin]
   • Strapi 5 also provides an experimental built-in OpenAPI CLI generator (strapi openapi generate) that produces an OpenAPI 3.1 spec from your app, independent of the Documentation plugin. [OpenAPI CLI]

   The docs do not explicitly state that either generator will automatically merge custom User fields and the register.allowedFields config into the /auth/local/register schema. Based on what you’re observing and what’s documented, it looks like the plugin is indeed not aware of register.allowedFields, so it documents only the default fields.

3. Current ways to adjust the generated docs

   With the Documentation plugin, there are three documented mechanisms to correct or enrich the generated OpenAPI:

   • registerOverride() – replace paths, tags, or components with your own definitions in your app’s or a plugin’s register lifecycle: [registerOverride]

     // e.g. src/index.js (application register lifecycle)
     module.exports = {
       register({ strapi }) {
         if (strapi.plugin('documentation')) {
           const override = {
             paths: {
               '/api/auth/local/register': {
                 post: {
                   // your corrected requestBody / schema here
                 },
               },
             },
           };
     
           strapi
             .plugin('documentation')
             .service('override')
             .registerOverride(override, {
               pluginOrigin: 'your-app',
             });
         }
       },
     };

   • excludeFromGeneration() – exclude specific APIs or plugins from generation if you want to fully manage them yourself. [excludeFromGeneration]

   • mutateDocumentation() – mutate the final generated spec in settings.json via x-strapi-config.mutateDocumentation, giving you “last word” access to the OpenAPI object: [mutateDocumentation]

     // src/extensions/documentation/config/settings.json
     {
       "openapi": "3.0.0",
       "info": {
         "version": "1.0.0",
         "title": "DOCUMENTATION"
       },
       "x-strapi-config": {
         "path": "/documentation",
         "plugins": ["upload", "users-permissions"],
         "mutateDocumentation": (generatedDocumentationDraft) => {
           // Example: tweak an existing path
           generatedDocumentationDraft.paths["/answer-to-everything"]
             .get.responses["200"].description = "*";
         }
       }
     }

   These are the same mechanisms you mentioned needing to use today, and the docs confirm that this is the only officially supported way for a plugin or app to alter what’s generated. [registerOverride; mutateDocumentation]

4. How this relates to your request

   The behavior you’re asking for—automatic inclusion of:

   • extra attributes declared on the extended User content-type, and
   • extra fields allowed at registration via register.allowedFields

   into the /auth/local/register documentation—is not documented as existing behavior in the current docs. The knowledge sources don’t mention any coupling between Users & Permissions’ register.allowedFields and the documentation (plugin or CLI) generators.

   So from the documentation we have, this is best treated as:

   • A missing capability / feature request for the documentation tooling, and
   • Potentially a bug in expected DX, since it causes a mismatch between the real API and the auto-generated docs.

5. Suggested next steps

   Given what’s documented:

   • For now, the only supported workaround is exactly what you described:

     • Keep your source of truth in the User schema and register.allowedFields, and
     • Use either registerOverride() or mutateDocumentation() to bring /auth/local/register in line with your real API.

   • Because this affects core behavior (auth endpoints and official docs tooling) and isn’t just a docs wording issue, it likely needs core team attention. I would recommend:

     • Opening or linking this to an issue in strapi/strapi so it can be tracked as:
       • either an enhancement (“documentation generator should reflect register.allowedFields”), or
       • a bug (“generated OpenAPI for /auth/local/register is inconsistent with configured registration fields”).

     Tagging for docs triage: @pwizla – this looks like something that may need to be surfaced or transferred to the main strapi/strapi repository for proper tracking.

   • If you’d like to push this as a formal feature request, you can also submit it on the public roadmap/feedback portal: https://feedback.strapi.io. [Community]

   • For further discussion or to see if other community members have patterns that reduce duplication, you might also get good input on:

     • The Forum: https://forum.strapi.io
     • Discord: https://discord.strapi.io [Community]

---

To summarise: the current docs confirm your need to configure register.allowedFields and show how to override or mutate the generated documentation, but they do not describe any automatic linkage between those registration fields and the /auth/local/register OpenAPI schema. Given the unmaintained status of the Documentation plugin for Strapi 5, your request is very reasonable and would be a meaningful improvement to developer experience.

📚 Relevant documentation:

• Community & Support
• Custom Fields - Usage
• Documentation plugin
• Documentation plugin - Code-based configuration
• Documentation plugin - mutateDocumentation()
• Documentation plugin - Overriding the generated documentation
• Documentation plugin - registerOverride()
• Documentation plugin - Usage
• Models - Custom fields
• OpenAPI specification generation
• Plugins extension
• Release notes - 6.2.0
• The Users & Permissions plugin's register.allowedFields configuration option defaults to []
• Users & Permissions - Registration configuration
• Users & Permissions - Usage

---

ℹ️ This response was generated automatically. If this doesn't fully answer your question or if you need further assistance, please mention @pwizla in a comment and a human maintainer will help you.

You can also try our interactive AI chat for more detailed assistance.

💡 For feature requests or product feedback, visit feedback.strapi.io.

[pwizla]

Hi @murschiid,
I'm getting back to you now, I was off sick last week.

Thank you very much for the detailed report and suggestions.

The AI-generated answer you received last week, while still containing valid content, might not fully satisfy you because the bot is only trained on documentation content. However, your issue is about the Documentation plugin, not the Strapi documentation website hosted at docs.strapi.io and who is the only purpose of the present repository.

The Documentation plugin is not maintained by the Strapi documentation team, but by Strapi core engineers, and is hosted in the strapi/strapi repository (see relevant files). You must address your request there.

I could transfer your issue myself, but there is a risk it would be closed automatically by their triage system because requests on strapi/strapi have to follow a specific template, which is not the same as in the present repository.

So, I will now close the present issue and invite you to create an issue on the strapi/strapi repository by clicking the New issue button on their issues page.

If you have specific questions or requests about the Strapi documentation website content, feel free to re-open this issue or create another one if the topic differs.

Thank you for your understanding, have a nice week!