chore: Add PR's requested changes and additional AI comments

Author: matiasperrone-exo

app/Http/Controllers/OAuth2/OAuth2ProviderController.php

@@ -92,7 +92,7 @@ public function __construct
             new OA\Parameter(name: 'state', in: 'query', required: false, description: 'Opaque state parameter returned in the redirect', schema: new OA\Schema(type: 'string')),
             new OA\Parameter(name: 'nonce', in: 'query', required: false, description: 'Nonce for ID token replay protection (OIDC)', schema: new OA\Schema(type: 'string')),
             new OA\Parameter(name: 'response_mode', in: 'query', required: false, description: 'Response mode override', schema: new OA\Schema(type: 'string', enum: ['query', 'fragment', 'form_post', 'direct'])),
-            new OA\Parameter(name: 'prompt', in: 'query', required: false, description: 'Space-delimited user interaction prompts (OIDC)', schema: new OA\Schema(type: 'string', enum: ['none', 'login', 'consent', 'select_account'])),
+            new OA\Parameter(name: 'prompt', in: 'query', required: false, description: 'Space-delimited user interaction prompts (OIDC). Allowed tokens: none, login, consent, select_account. "none" cannot be combined with others. Example: "login consent"', schema: new OA\Schema(type: 'string')),
             new OA\Parameter(name: 'login_hint', in: 'query', required: false, description: 'Hint about login identifier (OIDC)', schema: new OA\Schema(type: 'string')),
             new OA\Parameter(name: 'display', in: 'query', required: false, description: 'UI display preference (OIDC)', schema: new OA\Schema(type: 'string', enum: ['page', 'popup', 'touch', 'wap', 'native'])),
             new OA\Parameter(name: 'max_age', in: 'query', required: false, description: 'Maximum authentication age in seconds (OIDC)', schema: new OA\Schema(type: 'integer')),
@@ -255,7 +255,6 @@ public function auth()
         summary: 'OAuth2 Token Endpoint',
         description: 'Issues access tokens. Supports authorization_code, client_credentials, password, refresh_token, and passwordless grant types.',
         tags: ['OAuth2 / OpenID Connect'],
-        security: [['OAuth2ProviderSecurity' => []]],
         requestBody: new OA\RequestBody(
             description: 'Token request parameters',
             required: true,
@@ -423,7 +422,17 @@ public function certs()
         path: '/.well-known/openid-configuration',
         operationId: 'oauth2Discovery',
         summary: 'OpenID Connect Discovery Endpoint',
-        description: 'Returns the OpenID Provider Configuration document per OpenID Connect Discovery 1.0. Also available at /oauth2/.well-known/openid-configuration.',
+        description: 'Returns the OpenID Provider Configuration document per OpenID Connect Discovery 1.0.',
+        tags: ['OAuth2 / OpenID Connect'],
+        responses: [
+            new OA\Response(response: HttpResponse::HTTP_OK, description: 'OpenID Connect Discovery document', content: new OA\JsonContent(ref: '#/components/schemas/OpenIDDiscoveryResponse')),
+        ]
+    )]
+    #[OA\Get(
+        path: '/oauth2/.well-known/openid-configuration',
+        operationId: 'oauth2Discovery',
+        summary: 'OpenID Connect Discovery Endpoint',
+        description: 'Returns the OpenID Provider Configuration document per OpenID Connect Discovery 1.0.',
         tags: ['OAuth2 / OpenID Connect'],
         responses: [
             new OA\Response(response: HttpResponse::HTTP_OK, description: 'OpenID Connect Discovery document', content: new OA\JsonContent(ref: '#/components/schemas/OpenIDDiscoveryResponse')),

app/Swagger/OAuth2ProviderControllerSchemas.php

@@ -9,6 +9,7 @@
     title: 'OAuth2 Token Response',
     description: 'Successful token response per RFC 6749 §5.1',
     type: 'object',
+    required: ['access_token', 'token_type'],
     properties: [
         new OA\Property(property: 'access_token', type: 'string', description: 'The access token issued by the authorization server'),
         new OA\Property(property: 'token_type', type: 'string', description: 'The type of the token (typically Bearer)', example: 'Bearer'),
@@ -87,6 +88,7 @@ class OAuth2IntrospectionResponseSchema
     title: 'JSON Web Key Set',
     description: 'JWK Set document per RFC 7517',
     type: 'object',
+    required: ['keys'],
     properties: [
         new OA\Property(
             property: 'keys',
@@ -115,6 +117,7 @@ class JWKSResponseSchema
     title: 'OpenID Connect Discovery Document',
     description: 'OpenID Provider Configuration per OpenID Connect Discovery 1.0',
     type: 'object',
+    required: ['issuer', 'authorization_endpoint', 'token_endpoint', 'jwks_uri', 'response_types_supported', 'subject_types_supported', 'id_token_signing_alg_values_supported'],
     properties: [
         new OA\Property(property: 'issuer', type: 'string', format: 'uri', description: 'Issuer identifier URL'),
         new OA\Property(property: 'authorization_endpoint', type: 'string', format: 'uri', description: 'Authorization endpoint URL'),

app/Swagger/Requests/OAuth2AuthorizationRequestSchema.php

@@ -18,7 +18,7 @@
         new OA\Property(property: 'state', type: 'string', description: 'Opaque state parameter'),
         new OA\Property(property: 'nonce', type: 'string', description: 'Nonce for ID token replay protection'),
         new OA\Property(property: 'response_mode', type: 'string', description: 'Response mode override', enum: ['query', 'fragment', 'form_post', 'direct']),
-        new OA\Property(property: 'prompt', type: 'string', description: 'User interaction prompts'),
+        new OA\Property(property: 'prompt', type: 'string', description: 'Space-delimited user interaction prompts (OIDC). Allowed tokens: none, login, consent, select_account. "none" cannot be combined with others. Example: "login consent"'),
         new OA\Property(property: 'login_hint', type: 'string', description: 'Login identifier hint'),
         new OA\Property(property: 'code_challenge', type: 'string', description: 'PKCE code challenge'),
         new OA\Property(property: 'code_challenge_method', type: 'string', description: 'PKCE challenge method', enum: ['plain', 'S256']),