Skip to content

Feature | Extend Swagger Coverage for controller OAuth2TagsApiController #400

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
matiasperrone-exo wants to merge 7 commits into
base: main
Choose a base branch
from
+308 −16
Open

Feature | Extend Swagger Coverage for controller OAuth2TagsApiController #400

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7f1a942
feat: Extend Swagger Coverage for controller `OAuth2TagsApiController`
matiasperrone-exo Oct 13, 2025
df0753f
fix: param definition
matiasperrone-exo Oct 13, 2025
4834efb
fix: Change "namespace" word positioning
matiasperrone-exo Oct 14, 2025
6e11abd
feat: Add OAuth2 security scheme
matiasperrone Dec 3, 2025
aa54c7b
feat: Add changes requested in PR
matiasperrone Dec 4, 2025
b755506
feat: Add changes requested in PR
matiasperrone Dec 4, 2025
808ad49
chore: Add missing properties in TagSchema
matiasperrone Dec 29, 2025
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
241 changes: 239 additions & 2 deletions app/Http/Controllers/Apis/Protected/Main/OAuth2TagsApiController.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
<?php namespace App\Http\Controllers;
<?php

namespace App\Http\Controllers;

/**
* Copyright 2017 OpenStack Foundation
* Licensed under the Apache License, Version 2.0 (the "License");
Expand All @@ -12,13 +15,17 @@
* limitations under the License.
**/

use App\Models\Foundation\Main\IGroup;
use App\ModelSerializers\SerializerUtils;
use App\Security\SummitScopes;
use models\main\ITagRepository;
use models\oauth2\IResourceServerContext;
use Illuminate\Support\Facades\Validator;
use ModelSerializers\SerializerRegistry;
use Illuminate\Support\Facades\Request;
use App\Services\Model\ITagService;
use Illuminate\Http\Response;
use OpenApi\Attributes as OA;
/**
* Class OAuth2TagsApiController
* @package App\Http\Controllers
Expand Down Expand Up @@ -54,6 +61,61 @@ public function __construct
$this->tag_service = $tag_service;
}

#[OA\Get(
path: "/api/v1/tags",
operationId: "getAllTags",
summary: "Get all tags",
description: "Returns a paginated list of tags. Allows ordering, filtering and pagination.",
tags: ["Tags"],
security: [
[
'tags_oauth2' => [
SummitScopes::ReadAllSummitData,
SummitScopes::ReadSummitData,
SummitScopes::ReadTagsData,
]
]
],
parameters: [
new OA\Parameter(
name: 'page',
in: 'query',
required: false,
schema: new OA\Schema(type: 'integer'),
description: 'The page number'
),
new OA\Parameter(
name: 'per_page',
in: 'query',
required: false,
schema: new OA\Schema(type: 'integer'),
description: 'The number of pages in each page',
),
new OA\Parameter(
name: "filter[]",
in: "query",
required: false,
description: "Filter tags. Available filters: tag (=@, ==, @@)",
schema: new OA\Schema(type: "array", items: new OA\Items(type: "string")),
explode: true
),
new OA\Parameter(
name: "order",
in: "query",
required: false,
description: "Order by field. Valid fields: id, tag",
schema: new OA\Schema(type: "string")
),
],
responses: [
new OA\Response(
response: Response::HTTP_OK,
description: "Success",
content: new OA\JsonContent(ref: "#/components/schemas/PaginatedTagsResponse")
),
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
]
)]
public function getAll(){
return $this->_getAll(
function () {
Expand Down Expand Up @@ -88,6 +150,60 @@ function () {
);
}

#[OA\Get(
path: "/api/v1/tags/{id}",
operationId: "getTag",
summary: "Get a specific tag",
description: "Returns detailed information about a specific tag",
tags: ["Tags"],
security: [
[
'tags_oauth2' => [
SummitScopes::ReadAllSummitData,
SummitScopes::ReadSummitData,
SummitScopes::ReadTagsData,
]
]
],
parameters: [
new OA\Parameter(
name: "id",
in: "path",
required: true,
description: "Tag ID",
schema: new OA\Schema(type: "integer")
),
new OA\Parameter(
name: "expand",
in: "query",
required: false,
description: "Expand related entities",
schema: new OA\Schema(type: "string")
),
new OA\Parameter(
name: "fields",
in: "query",
required: false,
description: "Fields to include in response",
schema: new OA\Schema(type: "string")
),
new OA\Parameter(
name: "relations",
in: "query",
required: false,
description: "Relations to include",
schema: new OA\Schema(type: "string")
),
],
responses: [
new OA\Response(
response: Response::HTTP_OK,
description: "Success",
content: new OA\JsonContent(ref: "#/components/schemas/Tag")
),
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Tag not found"),
]
)]
public function getTag($tag_id){
return $this->processRequest(function () use ($tag_id) {
$tag = $this->repository->getById(intval($tag_id));
Expand All @@ -104,6 +220,43 @@ public function getTag($tag_id){
});
}

#[OA\Post(
path: "/api/v1/tags",
operationId: "createTag",
summary: "Create a new tag",
description: "Creates a new tag",
tags: ["Tags"],
x: [
'required-groups' => [
IGroup::SuperAdmins,
IGroup::Administrators,
IGroup::SummitAdministrators,
]
],
security: [
[
'tags_oauth2' => [
SummitScopes::WriteSummitData,
SummitScopes::WriteTagsData,
]
]
],
requestBody: new OA\RequestBody(
required: true,
content: new OA\JsonContent(ref: "#/components/schemas/TagRequest")
),
responses: [
new OA\Response(
response: Response::HTTP_CREATED,
description: "Created",
content: new OA\JsonContent(ref: "#/components/schemas/Tag")
),
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
]
)]
public function addTag(){
return $this->processRequest(function () {
if(!Request::isJson()) return $this->error400();
Expand Down Expand Up @@ -134,6 +287,53 @@ public function addTag(){
});
}

#[OA\Put(
path: "/api/v1/tags/{id}",
operationId: "updateTag",
summary: "Update a tag",
description: "Updates an existing tag",
tags: ["Tags"],
x: [
'required-groups' => [
IGroup::SuperAdmins,
IGroup::Administrators,
IGroup::SummitAdministrators,
]
],
security: [
[
'tags_oauth2' => [
SummitScopes::WriteSummitData,
SummitScopes::WriteTagsData,
]
]
],
parameters: [
new OA\Parameter(
name: "id",
in: "path",
required: true,
description: "Tag ID",
schema: new OA\Schema(type: "integer")
),
],
requestBody: new OA\RequestBody(
required: true,
content: new OA\JsonContent(ref: "#/components/schemas/TagRequest")
),
responses: [
new OA\Response(
response: Response::HTTP_OK,
description: "Success",
content: new OA\JsonContent(ref: "#/components/schemas/Tag")
),
new OA\Response(response: Response::HTTP_BAD_REQUEST, description: "Bad Request"),
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Tag not found"),
new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"),
]
)]
public function updateTag($tag_id){
return $this->processRequest(function () use ($tag_id) {
if(!Request::isJson()) return $this->error400();
Expand Down Expand Up @@ -166,6 +366,43 @@ public function updateTag($tag_id){
});
}

#[OA\Delete(
path: "/api/v1/tags/{id}",
operationId: "deleteTag",
summary: "Delete a tag",
description: "Deletes a tag",
tags: ["Tags"],
x: [
'required-groups' => [
IGroup::SuperAdmins,
IGroup::Administrators,
IGroup::SummitAdministrators,
]
],
security: [
[
'tags_oauth2' => [
SummitScopes::WriteSummitData,
SummitScopes::WriteTagsData,
]
]
],
parameters: [
new OA\Parameter(
name: "id",
in: "path",
required: true,
description: "Tag ID",
schema: new OA\Schema(type: "integer")
),
],
responses: [
new OA\Response(response: Response::HTTP_NO_CONTENT, description: "Deleted successfully"),
new OA\Response(response: Response::HTTP_UNAUTHORIZED, description: "Unauthorized"),
new OA\Response(response: Response::HTTP_FORBIDDEN, description: "Forbidden"),
new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Tag not found"),
]
)]
public function deleteTag($tag_id){
return $this->processRequest(function () use ($tag_id) {

Expand All @@ -174,4 +411,4 @@ public function deleteTag($tag_id){
return $this->deleted();
});
}
}
}
17 changes: 4 additions & 13 deletions app/Swagger/Models/TagSchema.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,19 +9,10 @@
type: "object",
required: ["id", "tag"],
properties: [
new OA\Property(
property: "id",
type: "integer",
format: "int64",
description: "Tag ID",
example: 1
),
new OA\Property(
property: "tag",
type: "string",
description: "Tag name/value",
example: "Beginner"
),
new OA\Property(property: "id", type: "integer", example: 1),
new OA\Property(property: "created", type: "integer", format: "int64", description: "Creation timestamp (epoch)", example: 1234567890),
new OA\Property(property: "last_edited", type: "integer", format: "int64", description: "Last edit timestamp (epoch)", example: 1234567890),
new OA\Property(property: "tag", type: "string", maxLength: 100, example: "Cloud Computing"),
]
)]
class TagSchema {}
27 changes: 27 additions & 0 deletions app/Swagger/Security/TagsAuthSchema.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<?php
namespace App\Swagger\schemas;

use App\Security\SummitScopes;
use OpenApi\Attributes as OA;

#[
OA\SecurityScheme(
type: 'oauth2',
securityScheme: 'tags_oauth2',
flows: [
new OA\Flow(
authorizationUrl: L5_SWAGGER_CONST_AUTH_URL,
tokenUrl: L5_SWAGGER_CONST_TOKEN_URL,
flow: 'authorizationCode',
scopes: [
SummitScopes::ReadAllSummitData => 'Read All Summit Data',
SummitScopes::ReadSummitData => 'Read Summit Data',
SummitScopes::ReadTagsData => 'Read Tags Data',
SummitScopes::WriteSummitData => 'Write Summit Data',
SummitScopes::WriteTagsData => 'Write Tags Data',
],
),
],
)
]
class TagsAuthSchema {}
Loading