From dfb8863ef217d48be8f2765bc456225cc1096468 Mon Sep 17 00:00:00 2001
From: matiasperrone-exo <matias.perrone@exomindset.co>
Date: Tue, 17 Feb 2026 21:22:50 +0000
Subject: [PATCH] feat: Add OpenAPI documentation on controller
 OAuth2ProviderController web routes

---
 .../OAuth2/OAuth2ProviderController.php       | 233 +++++++++++++++++-
 .../OAuth2ProviderControllerSchemas.php       | 172 +++++++++++++
 .../OAuth2AuthorizationRequestSchema.php      |  29 +++
 .../OAuth2EndSessionRequestSchema.php         |  22 ++
 .../OAuth2TokenIntrospectionRequestSchema.php |  21 ++
 .../Requests/OAuth2TokenRequestSchema.php     |  32 +++
 .../OAuth2TokenRevocationRequestSchema.php    |  22 ++
 ...OAuth2ProviderControllerSecuritySchema.php |  21 ++
 8 files changed, 551 insertions(+), 1 deletion(-)
 create mode 100644 app/Swagger/OAuth2ProviderControllerSchemas.php
 create mode 100644 app/Swagger/Requests/OAuth2AuthorizationRequestSchema.php
 create mode 100644 app/Swagger/Requests/OAuth2EndSessionRequestSchema.php
 create mode 100644 app/Swagger/Requests/OAuth2TokenIntrospectionRequestSchema.php
 create mode 100644 app/Swagger/Requests/OAuth2TokenRequestSchema.php
 create mode 100644 app/Swagger/Requests/OAuth2TokenRevocationRequestSchema.php
 create mode 100644 app/Swagger/Security/OAuth2ProviderControllerSecuritySchema.php

diff --git a/app/Http/Controllers/OAuth2/OAuth2ProviderController.php b/app/Http/Controllers/OAuth2/OAuth2ProviderController.php
index 285fc005..b7edbdbb 100644
--- a/app/Http/Controllers/OAuth2/OAuth2ProviderController.php
+++ b/app/Http/Controllers/OAuth2/OAuth2ProviderController.php
@@ -27,6 +27,8 @@
 use OAuth2\Requests\OAuth2TokenRevocationRequest;
 use OAuth2\Responses\OAuth2Response;
 use OAuth2\Strategies\OAuth2ResponseStrategyFactoryMethod;
+use OpenApi\Attributes as OA;
+use Symfony\Component\HttpFoundation\Response as HttpResponse;
 use Utils\Http\HttpContentType;
 use Utils\Services\IAuthService;
 use Illuminate\Support\Facades\Log;
@@ -76,6 +78,117 @@ public function __construct
      * use of the "POST" method as well.
      * @return mixed
      */
+    #[OA\Get(
+        path: '/oauth2/auth',
+        operationId: 'oauth2AuthorizeGet',
+        summary: 'OAuth2 Authorization Endpoint (GET)',
+        description: 'Initiates an OAuth2 authorization flow. Supports Authorization Code, Implicit, Hybrid, and OpenID Connect flows. Per RFC 6749 §3.1, GET is required.',
+        tags: ['OAuth2 / OpenID Connect'],
+        parameters: [
+            new OA\Parameter(name: 'response_type', in: 'query', required: true, description: 'OAuth2 response type', schema: new OA\Schema(type: 'string', enum: ['code', 'token', 'id_token', 'code token', 'code id_token', 'token id_token', 'code token id_token', 'otp', 'none'])),
+            new OA\Parameter(name: 'client_id', in: 'query', required: true, description: 'OAuth2 client identifier', schema: new OA\Schema(type: 'string')),
+            new OA\Parameter(name: 'redirect_uri', in: 'query', required: true, description: 'Redirect URI (must match a registered URI)', schema: new OA\Schema(type: 'string', format: 'uri')),
+            new OA\Parameter(name: 'scope', in: 'query', required: false, description: 'Space-delimited scopes (include "openid" for OIDC)', schema: new OA\Schema(type: 'string')),
+            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: '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')),
+            new OA\Parameter(name: 'acr_values', in: 'query', required: false, description: 'Authentication context class reference values (OIDC)', schema: new OA\Schema(type: 'string')),
+            new OA\Parameter(name: 'code_challenge', in: 'query', required: false, description: 'PKCE code challenge', schema: new OA\Schema(type: 'string')),
+            new OA\Parameter(name: 'code_challenge_method', in: 'query', required: false, description: 'PKCE challenge method', schema: new OA\Schema(type: 'string', enum: ['plain', 'S256'])),
+            new OA\Parameter(name: 'id_token_hint', in: 'query', required: false, description: 'Previously issued ID token hint (OIDC)', schema: new OA\Schema(type: 'string')),
+            new OA\Parameter(name: 'approval_prompt', in: 'query', required: false, description: 'Consent handling', schema: new OA\Schema(type: 'string', enum: ['auto', 'force'])),
+            new OA\Parameter(name: 'access_type', in: 'query', required: false, description: 'Token refresh behavior', schema: new OA\Schema(type: 'string', enum: ['online', 'offline'])),
+        ],
+        responses: [
+            new OA\Response(response: HttpResponse::HTTP_OK, description: 'Authorization request processed (response in body), depends on "response_mode" param'),
+            new OA\Response(response: HttpResponse::HTTP_FOUND, description: 'Redirect to client redirect_uri with authorization code, tokens, or error'),
+            new OA\Response(response: HttpResponse::HTTP_BAD_REQUEST, description: 'Bad Request', content: new OA\JsonContent(ref: '#/components/schemas/OAuth2ErrorResponse')),
+        ]
+    )]
+    #[OA\Post(
+        path: '/oauth2/auth',
+        operationId: 'oauth2AuthorizePost',
+        summary: 'OAuth2 Authorization Endpoint (POST)',
+        description: 'Initiates an OAuth2 authorization flow via POST. Same parameters as GET but sent as form data.',
+        tags: ['OAuth2 / OpenID Connect'],
+        requestBody: new OA\RequestBody(
+            description: 'Authorization request parameters',
+            required: true,
+            content: new OA\MediaType(
+                mediaType: 'application/x-www-form-urlencoded',
+                schema: new OA\Schema(ref: '#/components/schemas/OAuth2AuthorizationRequest')
+            )
+        ),
+        responses: [
+            new OA\Response(response: HttpResponse::HTTP_OK, description: 'Authorization request processed (response in body), depends on "response_mode" param'),
+            new OA\Response(response: HttpResponse::HTTP_FOUND, description: 'Redirect to client redirect_uri with authorization code, tokens, or error'),
+            new OA\Response(response: HttpResponse::HTTP_BAD_REQUEST, description: 'Bad Request', content: new OA\JsonContent(ref: '#/components/schemas/OAuth2ErrorResponse')),
+        ]
+    )]
+    #[OA\Put(
+        path: '/oauth2/auth',
+        operationId: 'oauth2AuthorizePut',
+        summary: 'OAuth2 Authorization Endpoint (PUT)',
+        description: 'Initiates an OAuth2 authorization flow via PUT. Same parameters as GET but sent as form data.',
+        tags: ['OAuth2 / OpenID Connect'],
+        requestBody: new OA\RequestBody(
+            description: 'Authorization request parameters',
+            required: true,
+            content: new OA\MediaType(
+                mediaType: 'application/x-www-form-urlencoded',
+                schema: new OA\Schema(ref: '#/components/schemas/OAuth2AuthorizationRequest')
+            )
+        ),
+        responses: [
+            new OA\Response(response: HttpResponse::HTTP_OK, description: 'Authorization request processed (response in body), depends on "response_mode" param'),
+            new OA\Response(response: HttpResponse::HTTP_FOUND, description: 'Redirect to client redirect_uri with authorization code, tokens, or error'),
+            new OA\Response(response: HttpResponse::HTTP_BAD_REQUEST, description: 'Bad Request', content: new OA\JsonContent(ref: '#/components/schemas/OAuth2ErrorResponse')),
+        ]
+    )]
+    #[OA\Patch(
+        path: '/oauth2/auth',
+        operationId: 'oauth2AuthorizePatch',
+        summary: 'OAuth2 Authorization Endpoint (PATCH)',
+        description: 'Initiates an OAuth2 authorization flow via PATCH. Same parameters as GET but sent as form data.',
+        tags: ['OAuth2 / OpenID Connect'],
+        requestBody: new OA\RequestBody(
+            description: 'Authorization request parameters',
+            required: true,
+            content: new OA\MediaType(
+                mediaType: 'application/x-www-form-urlencoded',
+                schema: new OA\Schema(ref: '#/components/schemas/OAuth2AuthorizationRequest')
+            )
+        ),
+        responses: [
+            new OA\Response(response: HttpResponse::HTTP_OK, description: 'Authorization request processed (response in body), depends on "response_mode" param'),
+            new OA\Response(response: HttpResponse::HTTP_FOUND, description: 'Redirect to client redirect_uri with authorization code, tokens, or error'),
+            new OA\Response(response: HttpResponse::HTTP_BAD_REQUEST, description: 'Bad Request', content: new OA\JsonContent(ref: '#/components/schemas/OAuth2ErrorResponse')),
+        ]
+    )]
+    #[OA\Delete(
+        path: '/oauth2/auth',
+        operationId: 'oauth2AuthorizeDelete',
+        summary: 'OAuth2 Authorization Endpoint (DELETE)',
+        description: 'Initiates an OAuth2 authorization flow via DELETE. Same parameters as GET but sent as form data.',
+        tags: ['OAuth2 / OpenID Connect'],
+        requestBody: new OA\RequestBody(
+            description: 'Authorization request parameters',
+            required: true,
+            content: new OA\MediaType(
+                mediaType: 'application/x-www-form-urlencoded',
+                schema: new OA\Schema(ref: '#/components/schemas/OAuth2AuthorizationRequest')
+            )
+        ),
+        responses: [
+            new OA\Response(response: HttpResponse::HTTP_OK, description: 'Authorization request processed (response in body), depends on "response_mode" param'),
+            new OA\Response(response: HttpResponse::HTTP_FOUND, description: 'Redirect to client redirect_uri with authorization code, tokens, or error'),
+            new OA\Response(response: HttpResponse::HTTP_BAD_REQUEST, description: 'Bad Request', content: new OA\JsonContent(ref: '#/components/schemas/OAuth2ErrorResponse')),
+        ]
+    )]
     public function auth()
     {
         try {
@@ -136,6 +249,26 @@ public function auth()
      * Token HTTP Endpoint
      * @return mixed
      */
+    #[OA\Post(
+        path: '/oauth2/token',
+        operationId: 'oauth2Token',
+        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,
+            content: new OA\MediaType(
+                mediaType: 'application/x-www-form-urlencoded',
+                schema: new OA\Schema(ref: '#/components/schemas/OAuth2TokenRequest')
+            )
+        ),
+        responses: [
+            new OA\Response(response: HttpResponse::HTTP_OK, description: 'Successful token response', content: new OA\JsonContent(ref: '#/components/schemas/OAuth2TokenResponse')),
+            new OA\Response(response: HttpResponse::HTTP_BAD_REQUEST, description: 'Token error', content: new OA\JsonContent(ref: '#/components/schemas/OAuth2ErrorResponse')),
+        ]
+    )]
     public function token()
     {
 
@@ -166,6 +299,26 @@ public function token()
      * Revoke Token HTTP Endpoint
      * @return mixed
      */
+    #[OA\Post(
+        path: '/oauth2/token/revoke',
+        operationId: 'oauth2RevokeToken',
+        summary: 'OAuth2 Token Revocation Endpoint',
+        description: 'Revokes an access token or refresh token per RFC 7009. The endpoint is idempotent — revoking a non-existent token returns success.',
+        tags: ['OAuth2 / OpenID Connect'],
+        security: [['OAuth2ProviderSecurity' => []]],
+        requestBody: new OA\RequestBody(
+            description: 'Token revocation parameters',
+            required: true,
+            content: new OA\MediaType(
+                mediaType: 'application/x-www-form-urlencoded',
+                schema: new OA\Schema(ref: '#/components/schemas/OAuth2TokenRevocationRequest')
+            )
+        ),
+        responses: [
+            new OA\Response(response: HttpResponse::HTTP_OK, description: 'Token successfully revoked'),
+            new OA\Response(response: HttpResponse::HTTP_BAD_REQUEST, description: 'Revocation error', content: new OA\JsonContent(ref: '#/components/schemas/OAuth2ErrorResponse')),
+        ]
+    )]
     public function revoke()
     {
         $response = $this->oauth2_protocol->revoke
@@ -196,6 +349,26 @@ public function revoke()
      * Introspection Token HTTP Endpoint
      * @return mixed
      */
+    #[OA\Post(
+        path: '/oauth2/token/introspection',
+        operationId: 'oauth2IntrospectToken',
+        summary: 'OAuth2 Token Introspection Endpoint',
+        description: 'Validates and returns metadata about an access token per RFC 7662. Returns detailed information about the token including associated user data.',
+        tags: ['OAuth2 / OpenID Connect'],
+        security: [['OAuth2ProviderSecurity' => []]],
+        requestBody: new OA\RequestBody(
+            description: 'Token introspection parameters',
+            required: true,
+            content: new OA\MediaType(
+                mediaType: 'application/x-www-form-urlencoded',
+                schema: new OA\Schema(ref: '#/components/schemas/OAuth2TokenIntrospectionRequest')
+            )
+        ),
+        responses: [
+            new OA\Response(response: HttpResponse::HTTP_OK, description: 'Token introspection response', content: new OA\JsonContent(ref: '#/components/schemas/OAuth2IntrospectionResponse')),
+            new OA\Response(response: HttpResponse::HTTP_BAD_REQUEST, description: 'Introspection error', content: new OA\JsonContent(ref: '#/components/schemas/OAuth2ErrorResponse')),
+        ]
+    )]
     public function introspection()
     {
 
@@ -226,6 +399,16 @@ public function introspection()
      *  OP's JSON Web Key Set [JWK] document.
      * @return string
      */
+    #[OA\Get(
+        path: '/oauth2/certs',
+        operationId: 'oauth2GetCerts',
+        summary: 'JSON Web Key Set (JWKS) Endpoint',
+        description: 'Returns the OpenID Provider JSON Web Key Set document containing public keys used for signing tokens (RFC 7517).',
+        tags: ['OAuth2 / OpenID Connect'],
+        responses: [
+            new OA\Response(response: HttpResponse::HTTP_OK, description: 'JWKS document', content: new OA\JsonContent(ref: '#/components/schemas/JWKSResponse')),
+        ]
+    )]
     public function certs()
     {
 
@@ -236,6 +419,16 @@ public function certs()
         return $response;
     }
 
+    #[OA\Get(
+        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.',
+        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')),
+        ]
+    )]
     public function discovery()
     {
 
@@ -258,6 +451,44 @@ public function checkSessionIFrame()
     /**
      * @see http://openid.net/specs/openid-connect-session-1_0.html#RPLogout
      */
+    #[OA\Get(
+        path: '/oauth2/end-session',
+        operationId: 'oauth2EndSessionGet',
+        summary: 'OpenID Connect End Session Endpoint (GET)',
+        description: 'Initiates RP-Initiated Logout per OpenID Connect Session Management 1.0. Terminates the user session and optionally redirects to the post-logout URI.',
+        tags: ['OAuth2 / OpenID Connect'],
+        parameters: [
+            new OA\Parameter(name: 'client_id', in: 'query', required: true, description: 'OAuth2 client identifier', schema: new OA\Schema(type: 'string')),
+            new OA\Parameter(name: 'id_token_hint', in: 'query', required: false, description: 'Previously issued ID token', schema: new OA\Schema(type: 'string')),
+            new OA\Parameter(name: 'post_logout_redirect_uri', in: 'query', required: false, description: 'URI to redirect after logout (must be registered)', schema: new OA\Schema(type: 'string', format: 'uri')),
+            new OA\Parameter(name: 'state', in: 'query', required: false, description: 'Opaque state parameter returned in the redirect', schema: new OA\Schema(type: 'string')),
+        ],
+        responses: [
+            new OA\Response(response: HttpResponse::HTTP_FOUND, description: 'Redirect to post_logout_redirect_uri'),
+            new OA\Response(response: HttpResponse::HTTP_OK, description: 'Session ended page (HTML)'),
+            new OA\Response(response: HttpResponse::HTTP_BAD_REQUEST, description: 'Invalid logout request', content: new OA\JsonContent(ref: '#/components/schemas/OAuth2ErrorResponse')),
+        ]
+    )]
+    #[OA\Post(
+        path: '/oauth2/end-session',
+        operationId: 'oauth2EndSessionPost',
+        summary: 'OpenID Connect End Session Endpoint (POST)',
+        description: 'Initiates RP-Initiated Logout via POST. Same parameters as GET but sent as form data.',
+        tags: ['OAuth2 / OpenID Connect'],
+        requestBody: new OA\RequestBody(
+            description: 'End session parameters',
+            required: true,
+            content: new OA\MediaType(
+                mediaType: 'application/x-www-form-urlencoded',
+                schema: new OA\Schema(ref: '#/components/schemas/OAuth2EndSessionRequest')
+            )
+        ),
+        responses: [
+            new OA\Response(response: HttpResponse::HTTP_FOUND, description: 'Redirect to post_logout_redirect_uri'),
+            new OA\Response(response: HttpResponse::HTTP_OK, description: 'Session ended page (HTML)'),
+            new OA\Response(response: HttpResponse::HTTP_BAD_REQUEST, description: 'Invalid logout request', content: new OA\JsonContent(ref: '#/components/schemas/OAuth2ErrorResponse')),
+        ]
+    )]
     public function endSession()
     {
         $request = new OAuth2LogoutRequest
@@ -285,4 +516,4 @@ public function endSession()
 
         return View::make('oauth2.session.session-ended');
     }
-} 
\ No newline at end of file
+}
\ No newline at end of file
diff --git a/app/Swagger/OAuth2ProviderControllerSchemas.php b/app/Swagger/OAuth2ProviderControllerSchemas.php
new file mode 100644
index 00000000..1b95a530
--- /dev/null
+++ b/app/Swagger/OAuth2ProviderControllerSchemas.php
@@ -0,0 +1,172 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'OAuth2TokenResponse',
+    title: 'OAuth2 Token Response',
+    description: 'Successful token response per RFC 6749 §5.1',
+    type: 'object',
+    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'),
+        new OA\Property(property: 'expires_in', type: 'integer', description: 'Lifetime of the access token in seconds', example: 3600),
+        new OA\Property(property: 'refresh_token', type: 'string', description: 'Refresh token (only if access_type=offline)', nullable: true),
+        new OA\Property(property: 'scope', type: 'string', description: 'Space-delimited list of granted scopes'),
+        new OA\Property(property: 'id_token', type: 'string', description: 'ID token JWT (only for OpenID Connect flows with openid scope)', nullable: true),
+    ]
+)]
+class OAuth2TokenResponseSchema
+{
+}
+
+#[OA\Schema(
+    schema: 'OAuth2ErrorResponse',
+    title: 'OAuth2 Error Response',
+    description: 'Error response per RFC 6749 §5.2',
+    type: 'object',
+    required: ['error'],
+    properties: [
+        new OA\Property(property: 'error', type: 'string', description: 'Error code', example: 'invalid_request'),
+        new OA\Property(property: 'error_description', type: 'string', description: 'Human-readable error description'),
+    ]
+)]
+class OAuth2ErrorResponseSchema
+{
+}
+
+#[OA\Schema(
+    schema: 'OAuth2IntrospectionResponse',
+    title: 'OAuth2 Token Introspection Response',
+    description: 'Token introspection response per RFC 7662',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'active', type: 'boolean', description: 'Whether the token is active'),
+        new OA\Property(property: 'access_token', type: 'string', description: 'The access token value'),
+        new OA\Property(property: 'client_id', type: 'string', description: 'Client identifier'),
+        new OA\Property(property: 'application_type', type: 'string', description: 'Client application type', enum: ['WEB', 'NATIVE', 'JS']),
+        new OA\Property(property: 'token_type', type: 'string', description: 'Token type', example: 'Bearer'),
+        new OA\Property(property: 'scope', type: 'string', description: 'Space-delimited scopes'),
+        new OA\Property(property: 'audience', type: 'string', description: 'Token audience'),
+        new OA\Property(property: 'expires_in', type: 'integer', description: 'Remaining lifetime in seconds'),
+        new OA\Property(property: 'user_id', type: 'integer', description: 'Resource owner user ID', nullable: true),
+        new OA\Property(property: 'user_identifier', type: 'string', description: 'Resource owner identifier', nullable: true),
+        new OA\Property(property: 'user_email', type: 'string', description: 'Resource owner email', nullable: true),
+        new OA\Property(property: 'user_first_name', type: 'string', description: 'Resource owner first name', nullable: true),
+        new OA\Property(property: 'user_last_name', type: 'string', description: 'Resource owner last name', nullable: true),
+        new OA\Property(property: 'user_pic', type: 'string', format: 'uri', description: 'Resource owner profile picture URL', nullable: true),
+        new OA\Property(
+            property: 'user_groups',
+            type: 'array',
+            description: 'Resource owner group memberships',
+            items: new OA\Items(
+                type: 'object',
+                properties: [
+                    new OA\Property(property: 'id', type: 'integer'),
+                    new OA\Property(property: 'title', type: 'string'),
+                    new OA\Property(property: 'description', type: 'string'),
+                ]
+            ),
+            nullable: true
+        ),
+        new OA\Property(property: 'user_email_verified', type: 'boolean', description: 'Whether the user email is verified', nullable: true),
+        new OA\Property(property: 'user_language', type: 'string', description: 'User preferred language', nullable: true),
+        new OA\Property(property: 'user_country', type: 'string', description: 'User country', nullable: true),
+        new OA\Property(property: 'allowed_return_uris', type: 'string', description: 'Space-delimited allowed return URIs'),
+        new OA\Property(property: 'allowed_origins', type: 'string', description: 'Space-delimited allowed origins'),
+    ]
+)]
+class OAuth2IntrospectionResponseSchema
+{
+}
+
+#[OA\Schema(
+    schema: 'JWKSResponse',
+    title: 'JSON Web Key Set',
+    description: 'JWK Set document per RFC 7517',
+    type: 'object',
+    properties: [
+        new OA\Property(
+            property: 'keys',
+            type: 'array',
+            description: 'Array of JSON Web Keys',
+            items: new OA\Items(
+                type: 'object',
+                properties: [
+                    new OA\Property(property: 'kty', type: 'string', description: 'Key type', example: 'RSA'),
+                    new OA\Property(property: 'kid', type: 'string', description: 'Key ID'),
+                    new OA\Property(property: 'use', type: 'string', description: 'Key usage', example: 'sig'),
+                    new OA\Property(property: 'alg', type: 'string', description: 'Algorithm', example: 'RS256'),
+                    new OA\Property(property: 'n', type: 'string', description: 'RSA modulus (Base64urlUInt-encoded)'),
+                    new OA\Property(property: 'e', type: 'string', description: 'RSA exponent (Base64urlUInt-encoded)', example: 'AQAB'),
+                ]
+            )
+        ),
+    ]
+)]
+class JWKSResponseSchema
+{
+}
+
+#[OA\Schema(
+    schema: 'OpenIDDiscoveryResponse',
+    title: 'OpenID Connect Discovery Document',
+    description: 'OpenID Provider Configuration per OpenID Connect Discovery 1.0',
+    type: 'object',
+    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'),
+        new OA\Property(property: 'token_endpoint', type: 'string', format: 'uri', description: 'Token endpoint URL'),
+        new OA\Property(property: 'userinfo_endpoint', type: 'string', format: 'uri', description: 'UserInfo endpoint URL'),
+        new OA\Property(property: 'revocation_endpoint', type: 'string', format: 'uri', description: 'Token revocation endpoint URL'),
+        new OA\Property(property: 'introspection_endpoint', type: 'string', format: 'uri', description: 'Token introspection endpoint URL'),
+        new OA\Property(property: 'jwks_uri', type: 'string', format: 'uri', description: 'JSON Web Key Set URL'),
+        new OA\Property(
+            property: 'scopes_supported',
+            type: 'array',
+            description: 'Supported OAuth2 scopes',
+            items: new OA\Items(type: 'string')
+        ),
+        new OA\Property(
+            property: 'response_types_supported',
+            type: 'array',
+            description: 'Supported response types',
+            items: new OA\Items(type: 'string')
+        ),
+        new OA\Property(
+            property: 'response_modes_supported',
+            type: 'array',
+            description: 'Supported response modes',
+            items: new OA\Items(type: 'string')
+        ),
+        new OA\Property(
+            property: 'grant_types_supported',
+            type: 'array',
+            description: 'Supported grant types',
+            items: new OA\Items(type: 'string')
+        ),
+        new OA\Property(
+            property: 'subject_types_supported',
+            type: 'array',
+            description: 'Supported subject types',
+            items: new OA\Items(type: 'string')
+        ),
+        new OA\Property(
+            property: 'id_token_signing_alg_values_supported',
+            type: 'array',
+            description: 'Supported ID token signing algorithms',
+            items: new OA\Items(type: 'string')
+        ),
+        new OA\Property(
+            property: 'code_challenge_methods_supported',
+            type: 'array',
+            description: 'Supported PKCE code challenge methods',
+            items: new OA\Items(type: 'string')
+        ),
+    ]
+)]
+class OpenIDDiscoveryResponseSchema
+{
+}
diff --git a/app/Swagger/Requests/OAuth2AuthorizationRequestSchema.php b/app/Swagger/Requests/OAuth2AuthorizationRequestSchema.php
new file mode 100644
index 00000000..edf9eeab
--- /dev/null
+++ b/app/Swagger/Requests/OAuth2AuthorizationRequestSchema.php
@@ -0,0 +1,29 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'OAuth2AuthorizationRequest',
+    title: 'OAuth2 Authorization Request',
+    description: 'Authorization request parameters per RFC 6749 §4.1.1 and OpenID Connect Core §3.1.2.1',
+    type: 'object',
+    required: ['response_type', 'client_id', 'redirect_uri'],
+    properties: [
+        new OA\Property(property: 'response_type', type: 'string', description: 'OAuth2 response type', enum: ['code', 'token', 'id_token', 'code token', 'code id_token', 'token id_token', 'code token id_token', 'otp', 'none']),
+        new OA\Property(property: 'client_id', type: 'string', description: 'OAuth2 client identifier'),
+        new OA\Property(property: 'redirect_uri', type: 'string', format: 'uri', description: 'Redirect URI'),
+        new OA\Property(property: 'scope', type: 'string', description: 'Space-delimited scopes'),
+        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: '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']),
+    ]
+)]
+class OAuth2AuthorizationRequestSchema
+{
+}
diff --git a/app/Swagger/Requests/OAuth2EndSessionRequestSchema.php b/app/Swagger/Requests/OAuth2EndSessionRequestSchema.php
new file mode 100644
index 00000000..4e4f8546
--- /dev/null
+++ b/app/Swagger/Requests/OAuth2EndSessionRequestSchema.php
@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'OAuth2EndSessionRequest',
+    title: 'OAuth2 End Session Request',
+    description: 'RP-Initiated Logout request parameters per OpenID Connect Session Management 1.0',
+    type: 'object',
+    required: ['client_id'],
+    properties: [
+        new OA\Property(property: 'client_id', type: 'string', description: 'OAuth2 client identifier'),
+        new OA\Property(property: 'id_token_hint', type: 'string', description: 'Previously issued ID token'),
+        new OA\Property(property: 'post_logout_redirect_uri', type: 'string', format: 'uri', description: 'URI to redirect after logout'),
+        new OA\Property(property: 'state', type: 'string', description: 'Opaque state parameter'),
+    ]
+)]
+class OAuth2EndSessionRequestSchema
+{
+}
diff --git a/app/Swagger/Requests/OAuth2TokenIntrospectionRequestSchema.php b/app/Swagger/Requests/OAuth2TokenIntrospectionRequestSchema.php
new file mode 100644
index 00000000..8588fed0
--- /dev/null
+++ b/app/Swagger/Requests/OAuth2TokenIntrospectionRequestSchema.php
@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'OAuth2TokenIntrospectionRequest',
+    title: 'OAuth2 Token Introspection Request',
+    description: 'Token introspection request parameters per RFC 7662 §2.1',
+    type: 'object',
+    required: ['token'],
+    properties: [
+        new OA\Property(property: 'token', type: 'string', description: 'The token to introspect'),
+        new OA\Property(property: 'client_id', type: 'string', description: 'Client identifier (if not using HTTP Basic auth)'),
+        new OA\Property(property: 'client_secret', type: 'string', description: 'Client secret (if not using HTTP Basic auth)'),
+    ]
+)]
+class OAuth2TokenIntrospectionRequestSchema
+{
+}
diff --git a/app/Swagger/Requests/OAuth2TokenRequestSchema.php b/app/Swagger/Requests/OAuth2TokenRequestSchema.php
new file mode 100644
index 00000000..5fe9f548
--- /dev/null
+++ b/app/Swagger/Requests/OAuth2TokenRequestSchema.php
@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'OAuth2TokenRequest',
+    title: 'OAuth2 Token Request',
+    description: 'Token request parameters per RFC 6749 §4.1.3. Fields required vary by grant_type.',
+    type: 'object',
+    required: ['grant_type'],
+    properties: [
+        new OA\Property(property: 'grant_type', type: 'string', description: 'OAuth2 grant type', enum: ['authorization_code', 'client_credentials', 'password', 'refresh_token', 'passwordless']),
+        new OA\Property(property: 'code', type: 'string', description: 'Authorization code (authorization_code grant)'),
+        new OA\Property(property: 'redirect_uri', type: 'string', format: 'uri', description: 'Redirect URI (must match the one used in authorization request)'),
+        new OA\Property(property: 'client_id', type: 'string', description: 'Client identifier (if not using HTTP Basic auth)'),
+        new OA\Property(property: 'client_secret', type: 'string', description: 'Client secret (if not using HTTP Basic auth)'),
+        new OA\Property(property: 'refresh_token', type: 'string', description: 'Refresh token (refresh_token grant)'),
+        new OA\Property(property: 'scope', type: 'string', description: 'Space-delimited scopes'),
+        new OA\Property(property: 'username', type: 'string', description: 'Username (password grant)'),
+        new OA\Property(property: 'password', type: 'string', description: 'Password (password grant)'),
+        new OA\Property(property: 'audience', type: 'string', description: 'Target audience (client_credentials grant)'),
+        new OA\Property(property: 'connection', type: 'string', description: 'Connection type (passwordless grant)', enum: ['sms', 'email', 'inline']),
+        new OA\Property(property: 'send', type: 'string', description: 'Delivery method (passwordless grant)', enum: ['code', 'link']),
+        new OA\Property(property: 'email', type: 'string', description: 'Email address (passwordless grant)'),
+        new OA\Property(property: 'phone_number', type: 'string', description: 'Phone number (passwordless grant)'),
+    ]
+)]
+class OAuth2TokenRequestSchema
+{
+}
diff --git a/app/Swagger/Requests/OAuth2TokenRevocationRequestSchema.php b/app/Swagger/Requests/OAuth2TokenRevocationRequestSchema.php
new file mode 100644
index 00000000..2ffc87e0
--- /dev/null
+++ b/app/Swagger/Requests/OAuth2TokenRevocationRequestSchema.php
@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'OAuth2TokenRevocationRequest',
+    title: 'OAuth2 Token Revocation Request',
+    description: 'Token revocation request parameters per RFC 7009 §2.1',
+    type: 'object',
+    required: ['token'],
+    properties: [
+        new OA\Property(property: 'token', type: 'string', description: 'The token to revoke'),
+        new OA\Property(property: 'token_type_hint', type: 'string', description: 'Hint about the token type', enum: ['access_token', 'refresh_token']),
+        new OA\Property(property: 'client_id', type: 'string', description: 'Client identifier (if not using HTTP Basic auth)'),
+        new OA\Property(property: 'client_secret', type: 'string', description: 'Client secret (if not using HTTP Basic auth)'),
+    ]
+)]
+class OAuth2TokenRevocationRequestSchema
+{
+}
diff --git a/app/Swagger/Security/OAuth2ProviderControllerSecuritySchema.php b/app/Swagger/Security/OAuth2ProviderControllerSecuritySchema.php
new file mode 100644
index 00000000..29e05df3
--- /dev/null
+++ b/app/Swagger/Security/OAuth2ProviderControllerSecuritySchema.php
@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+#[OA\SecurityScheme(
+    securityScheme: 'OAuth2ProviderSecurity',
+    type: 'oauth2',
+    description: 'OAuth2 client credentials authentication for protocol endpoints (token, revoke, introspection)',
+    flows: [
+        new OA\Flow(
+            flow: 'clientCredentials',
+            tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
+            scopes: []
+        ),
+    ]
+)]
+class OAuth2ProviderControllerSecuritySchema
+{
+}
\ No newline at end of file