Skip to content

Feature: Extend Swagger Coverage for controller ConfigurationsController #456

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+226 −0
Open

Feature: Extend Swagger Coverage for controller ConfigurationsController #456

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions app/Http/Controllers/ConfigurationsController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@
use Illuminate\Support\Facades\Route;
use models\utils\IEntity;
use ModelSerializers\SerializerRegistry;
use OpenApi\Attributes as OA;
use Symfony\Component\HttpFoundation\Response;
use Exception;
/**
* Class ConfigurationsController
Expand All @@ -42,6 +44,32 @@ public function __construct(IApiRepository $repository)
/**
* @return \Illuminate\Http\JsonResponse|mixed
*/
#[OA\Get(
path: '/.well-known/endpoints',
operationId: 'getEndpointsDefinitions',
description: 'Retrieve all available API endpoints definitions including OAuth2 and public endpoints',
tags: ['Configurations'],
parameters: [
new OA\Parameter(
name: 'expand',
description: 'Expansion parameters',
in: 'query',
required: false,
schema: new OA\Schema(type: 'string')
),
],
responses: [
new OA\Response(
response: Response::HTTP_OK,
description: 'List of all available endpoints',
content: new OA\JsonContent(ref: '#/components/schemas/EndpointsDefinitionsResponse')
),
new OA\Response(
response: Response::HTTP_INTERNAL_SERVER_ERROR,
description: 'Server Error'
),
]
)]
public function getEndpointsDefinitions(){
try {
$items = [];
Expand Down
198 changes: 198 additions & 0 deletions app/Swagger/ConfigurationsSchemas.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,198 @@
<?php
namespace App\Swagger\schemas;

use OpenApi\Attributes as OA;

#[OA\Schema(
schema: 'ApiScope',
type: 'object',
properties: [
new OA\Property(
property: 'id',
type: 'integer',
example: 1,
description: 'Scope ID'
),
new OA\Property(
property: 'name',
type: 'string',
example: 'read-all-summit-data',
description: 'Scope name'
),
new OA\Property(
property: 'description',
type: 'string',
example: 'Allows reading all summit data',
description: 'Scope description'
),
new OA\Property(
property: 'active',
type: 'boolean',
example: true,
description: 'Whether the scope is active'
),
]
)]
class ApiScopeSchema {}

#[OA\Schema(
schema: 'ApiEndpointAuthzGroup',
type: 'object',
properties: [
new OA\Property(
property: 'id',
type: 'integer',
example: 1,
description: 'Authorization group ID'
),
new OA\Property(
property: 'name',
type: 'string',
example: 'Administrators',
description: 'Authorization group name'
),
]
)]
class ApiEndpointAuthzGroupSchema {}

#[OA\Schema(
schema: 'ApiEndpoint',
type: 'object',
properties: [
new OA\Property(
property: 'id',
type: 'integer',
example: 1,
description: 'Endpoint ID'
),
new OA\Property(
property: 'name',
type: 'string',
example: 'get-summits',
description: 'Endpoint name'
),
new OA\Property(
property: 'description',
type: 'string',
example: 'Retrieve all summits',
description: 'Endpoint description'
),
new OA\Property(
property: 'active',
type: 'boolean',
example: true,
description: 'Whether the endpoint is active'
),
new OA\Property(
property: 'route',
type: 'string',
example: '/api/v1/summits',
description: 'Endpoint route'
),
new OA\Property(
property: 'http_method',
type: 'string',
example: 'GET',
description: 'HTTP method',
enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH']
),
new OA\Property(
property: 'scopes',
type: 'array',
items: new OA\Items(type: 'integer'),
description: 'Required OAuth2 scope IDs'
),
new OA\Property(
property: 'authz_groups',
type: 'array',
items: new OA\Items(type: 'integer'),
description: 'Required authorization group IDs'
),
]
)]
class ApiEndpointSchema {}

#[OA\Schema(
schema: 'Api',
type: 'object',
properties: [
new OA\Property(
property: 'id',
type: 'integer',
example: 1,
description: 'API ID'
),
new OA\Property(
property: 'name',
type: 'string',
example: 'summits',
description: 'API name'
),
new OA\Property(
property: 'description',
type: 'string',
example: 'Summit Management API',
description: 'API description'
),
new OA\Property(
property: 'active',
type: 'boolean',
example: true,
description: 'Whether the API is active'
),
new OA\Property(
property: 'scopes',
type: 'array',
items: new OA\Items(type: 'integer'),
description: 'API scope IDs'
),
new OA\Property(
property: 'endpoints',
type: 'array',
items: new OA\Items(type: 'integer'),
description: 'API endpoint IDs'
),
]
)]
class ApiSchema {}

#[OA\Schema(
schema: 'PublicEndpoint',
type: 'object',
properties: [
new OA\Property(
property: 'route',
type: 'string',
example: '/api/public/v1/timezones',
description: 'Public endpoint route'
),
new OA\Property(
property: 'http_methods',
type: 'array',
items: new OA\Items(type: 'string'),
example: ['GET'],
description: 'Available HTTP methods'
),
]
)]
class PublicEndpointSchema {}

#[OA\Schema(
schema: 'EndpointsDefinitionsResponse',
type: 'object',
properties: [
new OA\Property(
property: 'oauth2_endpoints',
type: 'array',
items: new OA\Items(ref: '#/components/schemas/Api'),
description: 'List of OAuth2 protected APIs with their endpoints'
),
new OA\Property(
property: 'public_endpoints',
type: 'array',
items: new OA\Items(ref: '#/components/schemas/PublicEndpoint'),
description: 'List of public endpoints'
),
]
)]
class EndpointsDefinitionsResponseSchema {}