feat: Enhance OpenAPI documentation by adding required field formatting and providing a description for the bearerAuth security scheme. (#1004)

* feat: Enhance OpenAPI documentation by adding required field formatting and providing a description for the bearerAuth security scheme.

* Apply suggestion from @ethanpalm

Co-authored-by: Ethan Palm <[email protected]>

* Apply suggestion from @ethanpalm

Co-authored-by: Ethan Palm <[email protected]>

---------

Co-authored-by: Ethan Palm <[email protected]>

Author: skeptrunedev

authentication-personalization/authentication-setup.mdx

@@ -103,7 +103,7 @@ Your documentation is hosted at `docs.foo.com` and your team uses the dashboard
       * **Authorization URL**: Your OAuth endpoint.
       * **Client ID**: Your OAuth 2.0 client identifier.
       * **Client Secret**: Your OAuth 2.0 client secret.
-      * **Scopes**: Permissions to request. Use multiple scopes if you need different access levels.
+      * **Scopes**: Permissions to request. Copy the **entire** scope string (for example, for a scope like `provider.users.docs`, copy the complete `provider.users.docs`). Use multiple scopes if you need different access levels.
       * **Token URL**: Your OAuth token exchange endpoint.
       * **Info API URL** (optional): Endpoint to retrieve user info for personalization. If omitted, the OAuth flow will only be used to verify identity and the user info will be empty.
       * **Logout URL**: The native logout URL for your OAuth provider. If your provider has a `returnTo` or similar parameter, point it back to your docs URL.
@@ -129,12 +129,12 @@ Your documentation is hosted at `foo.com/docs` and you have an existing OAuth se
 **Configure your OAuth server details** in your dashboard:
 - **Authorization URL**: `https://auth.foo.com/authorization`
 - **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH`
-- **Scopes**: `['docs-user-info']`
+- **Scopes**: `['provider.users.docs']`
 - **Token URL**: `https://auth.foo.com/exchange`
 - **Info API URL**: `https://api.foo.com/docs/user-info`
 - **Logout URL**: `https://auth.foo.com/logout?returnTo=https%3A%2F%2Ffoo.com%2Fdocs`
 
-**Create a user info endpoint** at `api.foo.com/docs/user-info`, which requires an OAuth access token with the `docs-user-info` scope, and returns:
+**Create a user info endpoint** at `api.foo.com/docs/user-info`, which requires an OAuth access token with the `provider.users.docs` scope, and returns:
 
 ```json
 {

authentication-personalization/personalization-setup.mdx

@@ -244,7 +244,7 @@ To redirect users to specific sections after login, use this URL format: `https:
     3. Select **OAuth** and configure these fields:
       * **Authorization URL**: Your OAuth authorization endpoint.
       * **Client ID**: Your OAuth 2.0 client identifier.
-      * **Scopes**: Permissions to request. Must match the scopes of the endpoint that you configured in the first step.
+      * **Scopes**: Permissions to request. Copy the **entire** scope string (for example, for a scope like `provider.users.docs`, copy the complete `provider.users.docs`). Must match the scopes of the endpoint that you configured in the first step.
       * **Token URL**: Your OAuth token exchange endpoint.
       * **Info API URL**: Endpoint to retrieve user data for personalization. Created in the first step.
     4. Select **Save changes**
@@ -259,7 +259,7 @@ To redirect users to specific sections after login, use this URL format: `https:
 
 Your documentation is hosted at `foo.com/docs` and you have an existing OAuth server that supports the PKCE flow. You want to personalize your docs based on user data.
 
-**Create a user info endpoint** at `api.foo.com/docs/user-info`, which requires an OAuth access token with the `docs-user-info` scope and responds with the user's custom data:
+**Create a user info endpoint** at `api.foo.com/docs/user-info`, which requires an OAuth access token with the `provider.users.docs` scope and responds with the user's custom data:
 
 ```json
 {