From 25b14150cc632ed866ca69765f6197abf100c254 Mon Sep 17 00:00:00 2001 From: Matias Perrone Date: Mon, 29 Sep 2025 14:19:18 -0300 Subject: [PATCH 1/5] feat: Add OpenAPI documentation to "getAll" method --- .../Apis/CountriesApiController.php | 53 +++++++++++++++++-- 1 file changed, 49 insertions(+), 4 deletions(-) diff --git a/app/Http/Controllers/Apis/CountriesApiController.php b/app/Http/Controllers/Apis/CountriesApiController.php index 1129f20eb..97fc6d60c 100644 --- a/app/Http/Controllers/Apis/CountriesApiController.php +++ b/app/Http/Controllers/Apis/CountriesApiController.php @@ -12,20 +12,65 @@ * limitations under the License. **/ use App\Models\Foundation\Main\CountryCodes; +use Illuminate\Http\Response; use Illuminate\Support\Facades\Log; use models\exceptions\EntityNotFoundException; use models\exceptions\ValidationException; +use OpenApi\Attributes as OA; use utils\PagingResponse; use Illuminate\Support\Facades\Request; + /** * Class CountriesApiController * @package App\Http\Controllers */ final class CountriesApiController extends JsonController { - /** - * @return mixed - */ + #[OA\Get( + path: "/api/v1/countries", + description: "Get all countries with ISO codes", + summary: 'Get all countries', + operationId: 'getAllCountries', + tags: ['country', 'countries', 'ISO'], + parameters: [ + new OA\Parameter( + name: 'expand', + in: 'query', + required: false, + description: 'Parameter for expanding related entity properties through serialization. Note: Has no effect on this endpoint since countries are returned as simple arrays, not complex entities. Always returns iso_code and name regardless of this parameter.', + schema: new OA\Schema(type: 'string', example: '') + ), + ], + responses: [ + new OA\Response( + response: 200, + description: 'Success - Returns paginated list of countries', + content: new OA\JsonContent( + properties: [ + 'total' => new OA\Property(property: 'total', type: 'integer', example: 195), + 'per_page' => new OA\Property(property: 'per_page', type: 'integer', example: 195), + 'current_page' => new OA\Property(property: 'current_page', type: 'integer', example: 1), + 'last_page' => new OA\Property(property: 'last_page', type: 'integer', example: 1), + 'data' => new OA\Property( + property: 'data', + type: 'array', + items: new OA\Items( + properties: [ + 'iso_code' => new OA\Property(property: 'iso_code', type: 'string', example: 'US'), + 'name' => new OA\Property(property: 'name', type: 'string', example: 'United States') + ], + type: 'object' + ) + ) + ], + type: 'object' + ) + ), + new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"), + new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"), + new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error") + ] + )] public function getAll(){ try { $countries = []; @@ -61,4 +106,4 @@ public function getAll(){ return $this->error500($ex); } } -} \ No newline at end of file +} From 1342a11369603129361c51ade373660d4d189088 Mon Sep 17 00:00:00 2001 From: Matias Perrone Date: Mon, 29 Sep 2025 15:03:41 -0300 Subject: [PATCH 2/5] fix: Open API path to endpoint --- app/Http/Controllers/Apis/CountriesApiController.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/Http/Controllers/Apis/CountriesApiController.php b/app/Http/Controllers/Apis/CountriesApiController.php index 97fc6d60c..9647d540f 100644 --- a/app/Http/Controllers/Apis/CountriesApiController.php +++ b/app/Http/Controllers/Apis/CountriesApiController.php @@ -27,7 +27,7 @@ final class CountriesApiController extends JsonController { #[OA\Get( - path: "/api/v1/countries", + path: "/api/public/v1/countries", description: "Get all countries with ISO codes", summary: 'Get all countries', operationId: 'getAllCountries', From c37432b6de766a5a2f9c3ab1b2665d4ed7001d51 Mon Sep 17 00:00:00 2001 From: Matias Perrone Date: Mon, 29 Sep 2025 18:54:53 -0300 Subject: [PATCH 3/5] fix: Use only one tag --- app/Http/Controllers/Apis/CountriesApiController.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/Http/Controllers/Apis/CountriesApiController.php b/app/Http/Controllers/Apis/CountriesApiController.php index 9647d540f..043d92b10 100644 --- a/app/Http/Controllers/Apis/CountriesApiController.php +++ b/app/Http/Controllers/Apis/CountriesApiController.php @@ -31,7 +31,7 @@ final class CountriesApiController extends JsonController description: "Get all countries with ISO codes", summary: 'Get all countries', operationId: 'getAllCountries', - tags: ['country', 'countries', 'ISO'], + tags: ['Country'], parameters: [ new OA\Parameter( name: 'expand', From 41031c19b6aa18d28ceef90b8ee46ddb233b9ac4 Mon Sep 17 00:00:00 2001 From: Matias Perrone Date: Tue, 30 Sep 2025 11:38:31 -0300 Subject: [PATCH 4/5] chore: Add ISOElementSchema --- app/Http/Controllers/Apis/CountriesApiController.php | 8 +------- app/Swagger/schemas.php | 11 ++++++++++- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/app/Http/Controllers/Apis/CountriesApiController.php b/app/Http/Controllers/Apis/CountriesApiController.php index 043d92b10..5fc79616b 100644 --- a/app/Http/Controllers/Apis/CountriesApiController.php +++ b/app/Http/Controllers/Apis/CountriesApiController.php @@ -54,13 +54,7 @@ final class CountriesApiController extends JsonController 'data' => new OA\Property( property: 'data', type: 'array', - items: new OA\Items( - properties: [ - 'iso_code' => new OA\Property(property: 'iso_code', type: 'string', example: 'US'), - 'name' => new OA\Property(property: 'name', type: 'string', example: 'United States') - ], - type: 'object' - ) + items: new OA\Items(ref: "#/components/schemas/ISOElementSchema") ) ], type: 'object' diff --git a/app/Swagger/schemas.php b/app/Swagger/schemas.php index 1eff77226..919ab2789 100644 --- a/app/Swagger/schemas.php +++ b/app/Swagger/schemas.php @@ -340,7 +340,6 @@ class RSVPUpdateRequestSchema_{ } - #[OA\Schema( schema: 'RSVPAdminAddRequest', type: 'object', @@ -351,3 +350,13 @@ class RSVPUpdateRequestSchema_{ ] )] class RSVPAdminAddRequestSchema {} + +#[OA\Schema( + schema: 'ISOElementSchema', + type: 'object', + properties: [ + 'iso_code' => new OA\Property(property: 'iso_code', type: 'string', example: 'US'), + 'name' => new OA\Property(property: 'name', type: 'string', example: 'United States') + ] +)] +class ISOElementSchema {}; From 4cbac93a8b304f2df1258d0b2bc065cb6420ee92 Mon Sep 17 00:00:00 2001 From: Matias Perrone Date: Wed, 1 Oct 2025 15:13:42 -0300 Subject: [PATCH 5/5] fix: Reuse already defined schema and add Paginated Schema --- .../Apis/CountriesApiController.php | 60 ++++--------------- app/Swagger/Countries.php | 32 ++++++++++ app/Swagger/schemas.php | 10 ---- 3 files changed, 45 insertions(+), 57 deletions(-) create mode 100644 app/Swagger/Countries.php diff --git a/app/Http/Controllers/Apis/CountriesApiController.php b/app/Http/Controllers/Apis/CountriesApiController.php index 5fc79616b..1e5bde224 100644 --- a/app/Http/Controllers/Apis/CountriesApiController.php +++ b/app/Http/Controllers/Apis/CountriesApiController.php @@ -11,14 +11,11 @@ * See the License for the specific language governing permissions and * limitations under the License. **/ + use App\Models\Foundation\Main\CountryCodes; use Illuminate\Http\Response; -use Illuminate\Support\Facades\Log; -use models\exceptions\EntityNotFoundException; -use models\exceptions\ValidationException; use OpenApi\Attributes as OA; use utils\PagingResponse; -use Illuminate\Support\Facades\Request; /** * Class CountriesApiController @@ -26,56 +23,37 @@ */ final class CountriesApiController extends JsonController { + use RequestProcessor; + #[OA\Get( path: "/api/public/v1/countries", description: "Get all countries with ISO codes", summary: 'Get all countries', operationId: 'getAllCountries', - tags: ['Country'], - parameters: [ - new OA\Parameter( - name: 'expand', - in: 'query', - required: false, - description: 'Parameter for expanding related entity properties through serialization. Note: Has no effect on this endpoint since countries are returned as simple arrays, not complex entities. Always returns iso_code and name regardless of this parameter.', - schema: new OA\Schema(type: 'string', example: '') - ), - ], + tags: ['Countries'], responses: [ new OA\Response( response: 200, description: 'Success - Returns paginated list of countries', - content: new OA\JsonContent( - properties: [ - 'total' => new OA\Property(property: 'total', type: 'integer', example: 195), - 'per_page' => new OA\Property(property: 'per_page', type: 'integer', example: 195), - 'current_page' => new OA\Property(property: 'current_page', type: 'integer', example: 1), - 'last_page' => new OA\Property(property: 'last_page', type: 'integer', example: 1), - 'data' => new OA\Property( - property: 'data', - type: 'array', - items: new OA\Items(ref: "#/components/schemas/ISOElementSchema") - ) - ], - type: 'object' - ) + content: new OA\JsonContent(ref: '#/components/schemas/PaginatedISOCountryElementResponseSchema'), ), new OA\Response(response: Response::HTTP_PRECONDITION_FAILED, description: "Validation Error"), new OA\Response(response: Response::HTTP_NOT_FOUND, description: "Not Found"), new OA\Response(response: Response::HTTP_INTERNAL_SERVER_ERROR, description: "Server Error") ] )] - public function getAll(){ - try { + public function getAll() + { + return $this->processRequest(function () { $countries = []; - foreach(CountryCodes::$iso_3166_countryCodes as $iso_code => $name){ + foreach (CountryCodes::$iso_3166_countryCodes as $iso_code => $name) { $countries[] = [ 'iso_code' => $iso_code, 'name' => $name, ]; } - $response = new PagingResponse + $response = new PagingResponse ( count($countries), count($countries), @@ -84,20 +62,8 @@ public function getAll(){ $countries ); - return $this->ok($response->toArray($expand = Request::input('expand',''))); - } - catch (ValidationException $ex1) { - Log::warning($ex1); - return $this->error412(array($ex1->getMessage())); - } - catch(EntityNotFoundException $ex2) - { - Log::warning($ex2); - return $this->error404(array('message'=> $ex2->getMessage())); - } - catch (\Exception $ex) { - Log::error($ex); - return $this->error500($ex); - } + return $this->ok($response->toArray()); + }); + } } diff --git a/app/Swagger/Countries.php b/app/Swagger/Countries.php new file mode 100644 index 000000000..49ecc8275 --- /dev/null +++ b/app/Swagger/Countries.php @@ -0,0 +1,32 @@ + new OA\Property(property: 'iso_code', type: 'string', example: 'US'), + 'name' => new OA\Property(property: 'name', type: 'string', example: 'United States') + ] +)] +class ISOElementSchema {}; + +#[OA\Schema( + schema: 'PaginatedISOCountryElementResponseSchema', + type: 'object', + allOf: [ + new OA\Schema(ref: '#/components/schemas/PaginateDataSchemaResponse'), + new OA\Schema( + type: 'object', + properties: [ + new OA\Property( + property: 'data', + type: 'array', + items: new OA\Items(ref: "#/components/schemas/ISOCountryElementSchema") + ) + ] + ) + ] +)] +class PaginatedISOElementResponseSchema {}; diff --git a/app/Swagger/schemas.php b/app/Swagger/schemas.php index 919ab2789..e2ec01a5a 100644 --- a/app/Swagger/schemas.php +++ b/app/Swagger/schemas.php @@ -350,13 +350,3 @@ class RSVPUpdateRequestSchema_{ ] )] class RSVPAdminAddRequestSchema {} - -#[OA\Schema( - schema: 'ISOElementSchema', - type: 'object', - properties: [ - 'iso_code' => new OA\Property(property: 'iso_code', type: 'string', example: 'US'), - 'name' => new OA\Property(property: 'name', type: 'string', example: 'United States') - ] -)] -class ISOElementSchema {};