Skip to content

Commit 5bf7fad

Browse files
matiasperrone-exomatiasperrone-exo
committed
feat: Add OpenAPI documentation on controller OAuth2ProviderController web routes
1 parent 0d6b7e3 commit 5bf7fad

8 files changed

Lines changed: 546 additions & 1 deletion

‎app/Http/Controllers/OAuth2/OAuth2ProviderController.php‎

Lines changed: 227 additions & 1 deletion
Large diffs are not rendered by default.

‎app/Swagger/OAuth2ProviderControllerSchemas.php‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'OAuth2TokenResponse',
9+
title: 'OAuth2 Token Response',
10+
description: 'Successful token response per RFC 6749 §5.1',
11+
type: 'object',
12+
properties: [
13+
new OA\Property(property: 'access_token', type: 'string', description: 'The access token issued by the authorization server'),
14+
new OA\Property(property: 'token_type', type: 'string', description: 'The type of the token (typically Bearer)', example: 'Bearer'),
15+
new OA\Property(property: 'expires_in', type: 'integer', description: 'Lifetime of the access token in seconds', example: 3600),
16+
new OA\Property(property: 'refresh_token', type: 'string', description: 'Refresh token (only if access_type=offline)', nullable: true),
17+
new OA\Property(property: 'scope', type: 'string', description: 'Space-delimited list of granted scopes'),
18+
new OA\Property(property: 'id_token', type: 'string', description: 'ID token JWT (only for OpenID Connect flows with openid scope)', nullable: true),
19+
]
20+
)]
21+
class OAuth2TokenResponseSchema
22+
{
23+
}
24+
25+
#[OA\Schema(
26+
schema: 'OAuth2ErrorResponse',
27+
title: 'OAuth2 Error Response',
28+
description: 'Error response per RFC 6749 §5.2',
29+
type: 'object',
30+
required: ['error'],
31+
properties: [
32+
new OA\Property(property: 'error', type: 'string', description: 'Error code', example: 'invalid_request'),
33+
new OA\Property(property: 'error_description', type: 'string', description: 'Human-readable error description'),
34+
]
35+
)]
36+
class OAuth2ErrorResponseSchema
37+
{
38+
}
39+
40+
#[OA\Schema(
41+
schema: 'OAuth2IntrospectionResponse',
42+
title: 'OAuth2 Token Introspection Response',
43+
description: 'Token introspection response per RFC 7662',
44+
type: 'object',
45+
properties: [
46+
new OA\Property(property: 'active', type: 'boolean', description: 'Whether the token is active'),
47+
new OA\Property(property: 'access_token', type: 'string', description: 'The access token value'),
48+
new OA\Property(property: 'client_id', type: 'string', description: 'Client identifier'),
49+
new OA\Property(property: 'application_type', type: 'string', description: 'Client application type', enum: ['WEB', 'NATIVE', 'JS']),
50+
new OA\Property(property: 'token_type', type: 'string', description: 'Token type', example: 'Bearer'),
51+
new OA\Property(property: 'scope', type: 'string', description: 'Space-delimited scopes'),
52+
new OA\Property(property: 'audience', type: 'string', description: 'Token audience'),
53+
new OA\Property(property: 'expires_in', type: 'integer', description: 'Remaining lifetime in seconds'),
54+
new OA\Property(property: 'user_id', type: 'integer', description: 'Resource owner user ID', nullable: true),
55+
new OA\Property(property: 'user_identifier', type: 'string', description: 'Resource owner identifier', nullable: true),
56+
new OA\Property(property: 'user_email', type: 'string', description: 'Resource owner email', nullable: true),
57+
new OA\Property(property: 'user_first_name', type: 'string', description: 'Resource owner first name', nullable: true),
58+
new OA\Property(property: 'user_last_name', type: 'string', description: 'Resource owner last name', nullable: true),
59+
new OA\Property(property: 'user_pic', type: 'string', format: 'uri', description: 'Resource owner profile picture URL', nullable: true),
60+
new OA\Property(
61+
property: 'user_groups',
62+
type: 'array',
63+
description: 'Resource owner group memberships',
64+
items: new OA\Items(
65+
type: 'object',
66+
properties: [
67+
new OA\Property(property: 'id', type: 'integer'),
68+
new OA\Property(property: 'title', type: 'string'),
69+
new OA\Property(property: 'description', type: 'string'),
70+
]
71+
),
72+
nullable: true
73+
),
74+
new OA\Property(property: 'user_email_verified', type: 'boolean', description: 'Whether the user email is verified', nullable: true),
75+
new OA\Property(property: 'user_language', type: 'string', description: 'User preferred language', nullable: true),
76+
new OA\Property(property: 'user_country', type: 'string', description: 'User country', nullable: true),
77+
new OA\Property(property: 'allowed_return_uris', type: 'string', description: 'Space-delimited allowed return URIs'),
78+
new OA\Property(property: 'allowed_origins', type: 'string', description: 'Space-delimited allowed origins'),
79+
]
80+
)]
81+
class OAuth2IntrospectionResponseSchema
82+
{
83+
}
84+
85+
#[OA\Schema(
86+
schema: 'JWKSResponse',
87+
title: 'JSON Web Key Set',
88+
description: 'JWK Set document per RFC 7517',
89+
type: 'object',
90+
properties: [
91+
new OA\Property(
92+
property: 'keys',
93+
type: 'array',
94+
description: 'Array of JSON Web Keys',
95+
items: new OA\Items(
96+
type: 'object',
97+
properties: [
98+
new OA\Property(property: 'kty', type: 'string', description: 'Key type', example: 'RSA'),
99+
new OA\Property(property: 'kid', type: 'string', description: 'Key ID'),
100+
new OA\Property(property: 'use', type: 'string', description: 'Key usage', example: 'sig'),
101+
new OA\Property(property: 'alg', type: 'string', description: 'Algorithm', example: 'RS256'),
102+
new OA\Property(property: 'n', type: 'string', description: 'RSA modulus (Base64urlUInt-encoded)'),
103+
new OA\Property(property: 'e', type: 'string', description: 'RSA exponent (Base64urlUInt-encoded)', example: 'AQAB'),
104+
]
105+
)
106+
),
107+
]
108+
)]
109+
class JWKSResponseSchema
110+
{
111+
}
112+
113+
#[OA\Schema(
114+
schema: 'OpenIDDiscoveryResponse',
115+
title: 'OpenID Connect Discovery Document',
116+
description: 'OpenID Provider Configuration per OpenID Connect Discovery 1.0',
117+
type: 'object',
118+
properties: [
119+
new OA\Property(property: 'issuer', type: 'string', format: 'uri', description: 'Issuer identifier URL'),
120+
new OA\Property(property: 'authorization_endpoint', type: 'string', format: 'uri', description: 'Authorization endpoint URL'),
121+
new OA\Property(property: 'token_endpoint', type: 'string', format: 'uri', description: 'Token endpoint URL'),
122+
new OA\Property(property: 'userinfo_endpoint', type: 'string', format: 'uri', description: 'UserInfo endpoint URL'),
123+
new OA\Property(property: 'revocation_endpoint', type: 'string', format: 'uri', description: 'Token revocation endpoint URL'),
124+
new OA\Property(property: 'introspection_endpoint', type: 'string', format: 'uri', description: 'Token introspection endpoint URL'),
125+
new OA\Property(property: 'jwks_uri', type: 'string', format: 'uri', description: 'JSON Web Key Set URL'),
126+
new OA\Property(
127+
property: 'scopes_supported',
128+
type: 'array',
129+
description: 'Supported OAuth2 scopes',
130+
items: new OA\Items(type: 'string')
131+
),
132+
new OA\Property(
133+
property: 'response_types_supported',
134+
type: 'array',
135+
description: 'Supported response types',
136+
items: new OA\Items(type: 'string')
137+
),
138+
new OA\Property(
139+
property: 'response_modes_supported',
140+
type: 'array',
141+
description: 'Supported response modes',
142+
items: new OA\Items(type: 'string')
143+
),
144+
new OA\Property(
145+
property: 'grant_types_supported',
146+
type: 'array',
147+
description: 'Supported grant types',
148+
items: new OA\Items(type: 'string')
149+
),
150+
new OA\Property(
151+
property: 'subject_types_supported',
152+
type: 'array',
153+
description: 'Supported subject types',
154+
items: new OA\Items(type: 'string')
155+
),
156+
new OA\Property(
157+
property: 'id_token_signing_alg_values_supported',
158+
type: 'array',
159+
description: 'Supported ID token signing algorithms',
160+
items: new OA\Items(type: 'string')
161+
),
162+
new OA\Property(
163+
property: 'code_challenge_methods_supported',
164+
type: 'array',
165+
description: 'Supported PKCE code challenge methods',
166+
items: new OA\Items(type: 'string')
167+
),
168+
]
169+
)]
170+
class OpenIDDiscoveryResponseSchema
171+
{
172+
}

‎app/Swagger/Requests/OAuth2AuthorizationRequestSchema.php‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'OAuth2AuthorizationRequest',
9+
title: 'OAuth2 Authorization Request',
10+
description: 'Authorization request parameters per RFC 6749 §4.1.1 and OpenID Connect Core §3.1.2.1',
11+
type: 'object',
12+
required: ['response_type', 'client_id', 'redirect_uri'],
13+
properties: [
14+
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']),
15+
new OA\Property(property: 'client_id', type: 'string', description: 'OAuth2 client identifier'),
16+
new OA\Property(property: 'redirect_uri', type: 'string', format: 'uri', description: 'Redirect URI'),
17+
new OA\Property(property: 'scope', type: 'string', description: 'Space-delimited scopes'),
18+
new OA\Property(property: 'state', type: 'string', description: 'Opaque state parameter'),
19+
new OA\Property(property: 'nonce', type: 'string', description: 'Nonce for ID token replay protection'),
20+
new OA\Property(property: 'response_mode', type: 'string', description: 'Response mode override', enum: ['query', 'fragment', 'form_post', 'direct']),
21+
new OA\Property(property: 'prompt', type: 'string', description: 'User interaction prompts'),
22+
new OA\Property(property: 'login_hint', type: 'string', description: 'Login identifier hint'),
23+
new OA\Property(property: 'code_challenge', type: 'string', description: 'PKCE code challenge'),
24+
new OA\Property(property: 'code_challenge_method', type: 'string', description: 'PKCE challenge method', enum: ['plain', 'S256']),
25+
]
26+
)]
27+
class OAuth2AuthorizationRequestSchema
28+
{
29+
}

‎app/Swagger/Requests/OAuth2EndSessionRequestSchema.php‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'OAuth2EndSessionRequest',
9+
title: 'OAuth2 End Session Request',
10+
description: 'RP-Initiated Logout request parameters per OpenID Connect Session Management 1.0',
11+
type: 'object',
12+
required: ['client_id'],
13+
properties: [
14+
new OA\Property(property: 'client_id', type: 'string', description: 'OAuth2 client identifier'),
15+
new OA\Property(property: 'id_token_hint', type: 'string', description: 'Previously issued ID token'),
16+
new OA\Property(property: 'post_logout_redirect_uri', type: 'string', format: 'uri', description: 'URI to redirect after logout'),
17+
new OA\Property(property: 'state', type: 'string', description: 'Opaque state parameter'),
18+
]
19+
)]
20+
class OAuth2EndSessionRequestSchema
21+
{
22+
}

‎app/Swagger/Requests/OAuth2TokenIntrospectionRequestSchema.php‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'OAuth2TokenIntrospectionRequest',
9+
title: 'OAuth2 Token Introspection Request',
10+
description: 'Token introspection request parameters per RFC 7662 §2.1',
11+
type: 'object',
12+
required: ['token'],
13+
properties: [
14+
new OA\Property(property: 'token', type: 'string', description: 'The token to introspect'),
15+
new OA\Property(property: 'client_id', type: 'string', description: 'Client identifier (if not using HTTP Basic auth)'),
16+
new OA\Property(property: 'client_secret', type: 'string', description: 'Client secret (if not using HTTP Basic auth)'),
17+
]
18+
)]
19+
class OAuth2TokenIntrospectionRequestSchema
20+
{
21+
}

‎app/Swagger/Requests/OAuth2TokenRequestSchema.php‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'OAuth2TokenRequest',
9+
title: 'OAuth2 Token Request',
10+
description: 'Token request parameters per RFC 6749 §4.1.3. Fields required vary by grant_type.',
11+
type: 'object',
12+
required: ['grant_type'],
13+
properties: [
14+
new OA\Property(property: 'grant_type', type: 'string', description: 'OAuth2 grant type', enum: ['authorization_code', 'client_credentials', 'password', 'refresh_token', 'passwordless']),
15+
new OA\Property(property: 'code', type: 'string', description: 'Authorization code (authorization_code grant)'),
16+
new OA\Property(property: 'redirect_uri', type: 'string', format: 'uri', description: 'Redirect URI (must match the one used in authorization request)'),
17+
new OA\Property(property: 'client_id', type: 'string', description: 'Client identifier (if not using HTTP Basic auth)'),
18+
new OA\Property(property: 'client_secret', type: 'string', description: 'Client secret (if not using HTTP Basic auth)'),
19+
new OA\Property(property: 'refresh_token', type: 'string', description: 'Refresh token (refresh_token grant)'),
20+
new OA\Property(property: 'scope', type: 'string', description: 'Space-delimited scopes'),
21+
new OA\Property(property: 'username', type: 'string', description: 'Username (password grant)'),
22+
new OA\Property(property: 'password', type: 'string', description: 'Password (password grant)'),
23+
new OA\Property(property: 'audience', type: 'string', description: 'Target audience (client_credentials grant)'),
24+
new OA\Property(property: 'connection', type: 'string', description: 'Connection type (passwordless grant)', enum: ['sms', 'email', 'inline']),
25+
new OA\Property(property: 'send', type: 'string', description: 'Delivery method (passwordless grant)', enum: ['code', 'link']),
26+
new OA\Property(property: 'email', type: 'string', description: 'Email address (passwordless grant)'),
27+
new OA\Property(property: 'phone_number', type: 'string', description: 'Phone number (passwordless grant)'),
28+
]
29+
)]
30+
class OAuth2TokenRequestSchema
31+
{
32+
}

‎app/Swagger/Requests/OAuth2TokenRevocationRequestSchema.php‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\Schema(
8+
schema: 'OAuth2TokenRevocationRequest',
9+
title: 'OAuth2 Token Revocation Request',
10+
description: 'Token revocation request parameters per RFC 7009 §2.1',
11+
type: 'object',
12+
required: ['token'],
13+
properties: [
14+
new OA\Property(property: 'token', type: 'string', description: 'The token to revoke'),
15+
new OA\Property(property: 'token_type_hint', type: 'string', description: 'Hint about the token type', enum: ['access_token', 'refresh_token']),
16+
new OA\Property(property: 'client_id', type: 'string', description: 'Client identifier (if not using HTTP Basic auth)'),
17+
new OA\Property(property: 'client_secret', type: 'string', description: 'Client secret (if not using HTTP Basic auth)'),
18+
]
19+
)]
20+
class OAuth2TokenRevocationRequestSchema
21+
{
22+
}

‎app/Swagger/Security/OAuth2ProviderControllerSecuritySchema.php‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<?php
2+
3+
namespace App\Swagger\schemas;
4+
5+
use OpenApi\Attributes as OA;
6+
7+
#[OA\SecurityScheme(
8+
securityScheme: 'OAuth2ProviderSecurity',
9+
type: 'oauth2',
10+
description: 'OAuth2 client credentials authentication for protocol endpoints (token, revoke, introspection)',
11+
flows: [
12+
new OA\Flow(
13+
flow: 'clientCredentials',
14+
tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
15+
scopes: []
16+
),
17+
]
18+
)]
19+
class OAuth2ProviderControllerSecuritySchema
20+
{
21+
}

0 commit comments

Comments
 (0)