Added OpenAPI docs using nelmioAPIDocBundle.

composer.json

@@ -14,6 +14,7 @@
         "doctrine/doctrine-migrations-bundle": "^3.3",
         "doctrine/orm": "^3.1",
         "easycorp/easyadmin-bundle": "^4.10",
+        "nelmio/api-doc-bundle": "^4.30",
         "nelmio/cors-bundle": "^2.4",
         "phpdocumentor/reflection-docblock": "^5.4",
         "phpstan/phpdoc-parser": "^1.28",

composer.lock

@@ -4,7 +4,7 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "7bf0ee6f0a2aa748adae16901e21b29b",
+    "content-hash": "20c33276e1944c7bb2e51459e4f90463",
     "packages": [
         {
             "name": "composer/semver",
@@ -1401,6 +1401,128 @@
             ],
             "time": "2024-04-19T18:13:15+00:00"
         },
+        {
+            "name": "nelmio/api-doc-bundle",
+            "version": "v4.30.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/nelmio/NelmioApiDocBundle.git",
+                "reference": "277fa17b912be31b5170e49f0924b1028058c938"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/nelmio/NelmioApiDocBundle/zipball/277fa17b912be31b5170e49f0924b1028058c938",
+                "reference": "277fa17b912be31b5170e49f0924b1028058c938",
+                "shasum": ""
+            },
+            "require": {
+                "ext-json": "*",
+                "php": ">=7.4",
+                "phpdocumentor/reflection-docblock": "^4.3.4 || ^5.0",
+                "phpdocumentor/type-resolver": "^1.8.2",
+                "psr/cache": "^1.0 || ^2.0 || ^3.0",
+                "psr/container": "^1.0 || ^2.0",
+                "psr/log": "^1.0 || ^2.0 || ^3.0",
+                "symfony/config": "^5.4 || ^6.4 || ^7.0",
+                "symfony/console": "^5.4 || ^6.4 || ^7.0",
+                "symfony/dependency-injection": "^5.4 || ^6.4 || ^7.0",
+                "symfony/deprecation-contracts": "^2.1 || ^3",
+                "symfony/framework-bundle": "^5.4.24 || ^6.4 || ^7.0",
+                "symfony/http-foundation": "^5.4 || ^6.4 || ^7.0",
+                "symfony/http-kernel": "^5.4 || ^6.4 || ^7.0",
+                "symfony/options-resolver": "^5.4 || ^6.4 || ^7.0",
+                "symfony/property-info": "^5.4.10 || ^6.4 || ^7.0",
+                "symfony/routing": "^5.4 || ^6.4 || ^7.0",
+                "zircote/swagger-php": "^4.6.1"
+            },
+            "conflict": {
+                "zircote/swagger-php": "4.8.7"
+            },
+            "require-dev": {
+                "api-platform/core": "^2.7.0 || ^3",
+                "composer/package-versions-deprecated": "1.11.99.1",
+                "doctrine/annotations": "^2.0",
+                "friendsofphp/php-cs-fixer": "^3.52",
+                "friendsofsymfony/rest-bundle": "^2.8 || ^3.0",
+                "jms/serializer": "^1.14 || ^3.0",
+                "jms/serializer-bundle": "^2.3 || ^3.0 || ^4.0 || ^5.0",
+                "phpstan/phpstan": "^1.10",
+                "phpstan/phpstan-phpunit": "^1.3",
+                "phpstan/phpstan-strict-rules": "^1.5",
+                "phpstan/phpstan-symfony": "^1.3",
+                "phpunit/phpunit": "^9.6 || ^10.5",
+                "symfony/asset": "^5.4 || ^6.4 || ^7.0",
+                "symfony/browser-kit": "^5.4 || ^6.4 || ^7.0",
+                "symfony/cache": "^5.4 || ^6.4 || ^7.0",
+                "symfony/dom-crawler": "^5.4 || ^6.4 || ^7.0",
+                "symfony/expression-language": "^5.4 || ^6.4 || ^7.0",
+                "symfony/form": "^5.4 || ^6.4 || ^7.0",
+                "symfony/phpunit-bridge": "^6.4",
+                "symfony/property-access": "^5.4 || ^6.4 || ^7.0",
+                "symfony/security-csrf": "^5.4 || ^6.4 || ^7.0",
+                "symfony/serializer": "^5.4 || ^6.4 || ^7.0",
+                "symfony/stopwatch": "^5.4 || ^6.4 || ^7.0",
+                "symfony/templating": "^5.4 || ^6.4 || ^7.0",
+                "symfony/twig-bundle": "^5.4 || ^6.4 || ^7.0",
+                "symfony/uid": "^5.4 || ^6.4 || ^7.0",
+                "symfony/validator": "^5.4 || ^6.4 || ^7.0",
+                "willdurand/hateoas-bundle": "^1.0 || ^2.0"
+            },
+            "suggest": {
+                "api-platform/core": "For using an API oriented framework.",
+                "doctrine/annotations": "For using doctrine annotations",
+                "friendsofsymfony/rest-bundle": "For using the parameters annotations.",
+                "jms/serializer-bundle": "For describing your models.",
+                "symfony/asset": "For using the Swagger UI.",
+                "symfony/cache": "For using a PSR-6 compatible cache implementation with the API doc generator.",
+                "symfony/form": "For describing your form type models.",
+                "symfony/monolog-bundle": "For using a PSR-3 compatible logger implementation with the API PHP describer.",
+                "symfony/security-csrf": "For using csrf protection tokens in forms.",
+                "symfony/serializer": "For describing your models.",
+                "symfony/twig-bundle": "For using the Swagger UI.",
+                "symfony/validator": "For describing the validation constraints in your models.",
+                "willdurand/hateoas-bundle": "For extracting HATEOAS metadata."
+            },
+            "type": "symfony-bundle",
+            "extra": {
+                "branch-alias": {
+                    "dev-master": "4.x-dev"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "Nelmio\\ApiDocBundle\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Symfony Community",
+                    "homepage": "https://github.com/nelmio/NelmioApiDocBundle/contributors"
+                }
+            ],
+            "description": "Generates documentation for your REST API from annotations and attributes",
+            "keywords": [
+                "api",
+                "doc",
+                "documentation",
+                "rest"
+            ],
+            "support": {
+                "issues": "https://github.com/nelmio/NelmioApiDocBundle/issues",
+                "source": "https://github.com/nelmio/NelmioApiDocBundle/tree/v4.30.0"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/DjordyKoert",
+                    "type": "github"
+                }
+            ],
+            "time": "2024-09-14T10:54:47+00:00"
+        },
         {
             "name": "nelmio/cors-bundle",
             "version": "2.4.0",
@@ -6730,6 +6852,87 @@
                 "source": "https://github.com/webmozarts/assert/tree/1.11.0"
             },
             "time": "2022-06-03T18:03:27+00:00"
+        },
+        {
+            "name": "zircote/swagger-php",
+            "version": "4.10.6",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/zircote/swagger-php.git",
+                "reference": "e462ff5269ea0ec91070edd5d51dc7215bdea3b6"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/zircote/swagger-php/zipball/e462ff5269ea0ec91070edd5d51dc7215bdea3b6",
+                "reference": "e462ff5269ea0ec91070edd5d51dc7215bdea3b6",
+                "shasum": ""
+            },
+            "require": {
+                "ext-json": "*",
+                "php": ">=7.2",
+                "psr/log": "^1.1 || ^2.0 || ^3.0",
+                "symfony/deprecation-contracts": "^2 || ^3",
+                "symfony/finder": ">=2.2",
+                "symfony/yaml": ">=3.3"
+            },
+            "require-dev": {
+                "composer/package-versions-deprecated": "^1.11",
+                "doctrine/annotations": "^1.7 || ^2.0",
+                "friendsofphp/php-cs-fixer": "^2.17 || ^3.47.1",
+                "phpstan/phpstan": "^1.6",
+                "phpunit/phpunit": ">=8",
+                "vimeo/psalm": "^4.23"
+            },
+            "suggest": {
+                "doctrine/annotations": "^1.7 || ^2.0"
+            },
+            "bin": [
+                "bin/openapi"
+            ],
+            "type": "library",
+            "extra": {
+                "branch-alias": {
+                    "dev-master": "4.x-dev"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "OpenApi\\": "src"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "Apache-2.0"
+            ],
+            "authors": [
+                {
+                    "name": "Robert Allen",
+                    "email": "[email protected]"
+                },
+                {
+                    "name": "Bob Fanger",
+                    "email": "[email protected]",
+                    "homepage": "https://bfanger.nl"
+                },
+                {
+                    "name": "Martin Rademacher",
+                    "email": "[email protected]",
+                    "homepage": "https://radebatz.net"
+                }
+            ],
+            "description": "swagger-php - Generate interactive documentation for your RESTful API using phpdoc annotations",
+            "homepage": "https://github.com/zircote/swagger-php/",
+            "keywords": [
+                "api",
+                "json",
+                "rest",
+                "service discovery"
+            ],
+            "support": {
+                "issues": "https://github.com/zircote/swagger-php/issues",
+                "source": "https://github.com/zircote/swagger-php/tree/4.10.6"
+            },
+            "time": "2024-07-26T03:04:43+00:00"
         }
     ],
     "packages-dev": [

config/bundles.php

@@ -11,4 +11,5 @@ return [
     EasyCorp\Bundle\EasyAdminBundle\EasyAdminBundle::class => ['all' => true],
     Nelmio\CorsBundle\NelmioCorsBundle::class => ['all' => true],
     Twig\Extra\TwigExtraBundle\TwigExtraBundle::class => ['all' => true],
+    Nelmio\ApiDocBundle\NelmioApiDocBundle::class => ['all' => true],
 ];

config/packages/nelmio_api_doc.yaml

@@ -0,0 +1,9 @@
+nelmio_api_doc:
+    documentation:
+        info:
+            title: SomniaRooms
+            description: A FOSS Hotel room booking system.
+            version: 1.0.0
+    areas: # to filter documented areas
+        path_patterns:
+            - ^/api(?!/doc$) # Accepts routes under /api except /api/doc

config/routes/nelmio_api_doc.yaml

@@ -0,0 +1,10 @@
+# Expose your documentation as JSON swagger compliant
+app.swagger:
+    path: /api/doc.json
+    methods: GET
+    defaults: { _controller: nelmio_api_doc.controller.swagger }
+
+app.swagger_ui:
+   path: /api/swagger
+   methods: GET
+   defaults: { _controller: nelmio_api_doc.controller.swagger_ui }

src/Controller/BookingController.php

@@ -8,17 +8,40 @@ use App\Entity\BookingRoom;
 use App\Repository\BookingRepository;
 use App\Repository\RoomCategoryRepository;
 use App\Repository\RoomAvailabilityRepository;
+use App\Request\BookingCreateRequest;
+use App\Request\BookingDetailsRequest;
+use App\Response\BookingCreateResponse;
 use App\Service\PricesService;
 use Doctrine\ORM\EntityManagerInterface;
+use Nelmio\ApiDocBundle\Annotation\Model;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 use Symfony\Component\HttpFoundation\JsonResponse;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpKernel\Exception\HttpException;
 use Symfony\Component\Routing\Attribute\Route;
+use OpenApi\Attributes as OA;
 
 class BookingController extends AbstractController
 {
-    #[Route('/api/booking/details', name: 'app_booking_details')]
+    /**
+     * Get booking details
+     */
+    #[Route('/api/booking/details', name: 'app_booking_details', methods: ["POST"])]
+    #[OA\Tag(name: "Booking")]
+    #[OA\Response(
+        response: 200,
+        description: 'Returns booking details',
+        content: new OA\JsonContent(
+            type: 'object',
+            ref: new Model(type: Booking::class),
+        )
+    )]
+    #[OA\RequestBody(
+        content: new OA\JsonContent(
+            type: 'object',
+            ref: new Model(type: BookingDetailsRequest::class),
+        )
+    )]
     public function getBookingDetails(Request $request, BookingRepository $repoBooking): JsonResponse
     {
         $payload = $request->toArray();
@@ -42,14 +65,32 @@ class BookingController extends AbstractController
         return $this->json($customerBooking);
     }
 
-    #[Route('/api/booking/create', name: 'app_booking_create')]
+    /**
+     * Create a new Booking.
+     */
+    #[Route('/api/booking/create', name: 'app_booking_create', methods: ["POST"])]
+    #[OA\Tag(name: "Booking")]
+    #[OA\Response(
+        response: 200,
+        description: 'Returns booking details',
+        content: new OA\JsonContent(
+            type: 'object',
+            ref: new Model(type: BookingCreateResponse::class)
+        )
+    )]
+    #[OA\RequestBody(
+        content: new OA\JsonContent(
+            type: 'object',
+            ref: new Model(type: BookingCreateRequest::class),
+        )
+    )]
     public function newBooking(Request $request, BookingRepository $repoBooking, EntityManagerInterface $entityManager, 
         RoomCategoryRepository $repoCat, RoomAvailabilityRepository $repoAvailability,
         PricesService $priceSrv): JsonResponse
     {
         $payload = $request->toArray();
         if (\is_null($payload)) {
-            throw new \Exception('Invalid Payload', 400);
+            throw new HttpException('Invalid Payload', 400);
         }
 
 
@@ -136,8 +177,10 @@ class BookingController extends AbstractController
                 }
                 
                 if(!$priceFound) {
-                    throw new HttpException(500, 
+                    throw new HttpException(
-                        "No se puedo obtener el precio para la categoría: " . $roommCategory->getId() . " , guests: " . $selecctedGuestAmount);
+                        500,
+                        "No se puedo obtener el precio para la categoría: " . $roomCategory->getId() . " , guests: " . $selectedGuestAmount
+                    );
                 }
 
                 $entityManager->persist($room);

src/Controller/ConfigVariableController.php

@@ -2,14 +2,35 @@
 
 namespace App\Controller;
 
+use App\Entity\ConfigVariable;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\Routing\Attribute\Route;
 use App\Repository\ConfigVariableRepository;
+use Nelmio\ApiDocBundle\Annotation\Model;
+use OpenApi\Attributes as OA;
 
 class ConfigVariableController extends AbstractController
 {
-    #[Route('/api/config', name: 'app_config_variable')]
+    /**
+     * Get All config variables.
+     */
+    #[Route('/api/config', name: 'app_config_allVariable', methods: ["GET"])]
+    #[OA\Tag(name: "Config")]
+    #[OA\Response(
+        response: 200,
+        description: 'Returns all public config variables.',
+        content: new OA\JsonContent(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: "results",
+                    type: "array",
+                    items: new OA\Items(ref: new Model(type: ConfigVariable::class))
+                )
+            ]
+        )
+    )]
     public function getAllVariables(ConfigVariableRepository $repo): Response
     {
         $varList = $repo->findAllVariables();
@@ -17,7 +38,22 @@ class ConfigVariableController extends AbstractController
         return $this->json(['results' => $varList]);
     }
 
-    #[Route('/api/config/section', name: 'app_config_sections')]
+    #[Route('/api/config/section', name: 'app_config_sections', methods: ["GET"])]
+    #[OA\Tag(name: "Config")]
+    #[OA\Response(
+        response: 200,
+        description: 'Returns all public config sections.',
+        content: new OA\JsonContent(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: "results",
+                    type: "array",
+                    items: new OA\Items(type: "string")
+                )
+            ]
+        )
+    )]
     public function getSections(ConfigVariableRepository $repo): Response
     {
         $sectionList = $repo->getAllSections();
@@ -30,7 +66,28 @@ class ConfigVariableController extends AbstractController
         return $this->json(['results' => $returnList]);
     }
 
-    #[Route('/api/config/section/{section}', name: 'app_config_variableBySection')]
+    #[Route('/api/config/section/{section}', name: 'app_config_variableBySection', methods: ["GET"])]
+    #[OA\Tag(name: "Config")]
+    #[OA\Response(
+        response: 200,
+        description: 'Returns all public config variables for given section.',
+        content: new OA\JsonContent(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: "results",
+                    type: "array",
+                    items: new OA\Items(ref: new Model(type: ConfigVariable::class))
+                )
+            ]
+        )
+    )]
+    #[OA\Parameter(
+        name: 'section',
+        in: 'path',
+        description: 'Config section.',
+        schema: new OA\Schema(type: 'string')
+    )]
     public function getVariablesBySection(ConfigVariableRepository $repo, string $section): Response
     {
         if(\is_null($section) || $section == '') {
@@ -42,7 +99,22 @@ class ConfigVariableController extends AbstractController
         return $this->json(['results' => $varList]);
     }
 
-    #[Route('/api/config/var/{key}', name: 'app_config_variable')]
+    #[Route('/api/config/var/{key}', name: 'app_config_variable', methods: ["GET"])]
+    #[OA\Tag(name: "Config")]
+    #[OA\Response(
+        response: 200,
+        description: 'Get config variable by key.',
+        content: new OA\JsonContent(
+            type: 'object',
+            ref: new Model(type: ConfigVariable::class),
+        )
+    )]
+    #[OA\Parameter(
+        name: 'key',
+        in: 'path',
+        description: 'Variable key.',
+        schema: new OA\Schema(type: 'string')
+    )]
     public function getByKey(ConfigVariableRepository $repo, string $key): Response
     {
         $var = $repo->findVariableByKey($key);

src/Controller/RoomCategoryController.php

@@ -7,16 +7,36 @@ use Doctrine\ORM\EntityManagerInterface;
 use App\Repository\RoomCategoryRepository;
 use App\Entity\RoomCategory;
 use App\Entity\RoomCategoryPhoto;
+use Nelmio\ApiDocBundle\Annotation\Model;
+use OpenApi\Annotations\Property;
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\HttpFoundation\JsonResponse;
 use Symfony\Component\Routing\Attribute\Route;
-use Symfony\Component\Serializer\SerializerInterface;
+use OpenApi\Attributes as OA;
-use Symfony\Component\Serializer\Context\Normalizer\ObjectNormalizerContextBuilder;
+use Symfony\Component\HttpKernel\Exception\HttpException;
 
 class RoomCategoryController extends AbstractController
 {
 
-    #[Route('/api/room/category', name: 'app_room_AllCategories')]
+    /**
+     * Get All room categories.
+     */
+    #[Route('/api/room/category', name: 'app_room_AllCategories', methods: ["GET"])]
+    #[OA\Tag(name: "Rooms")]
+    #[OA\Response(
+        response: 200,
+        description: 'Returns all room categories',
+        content: new OA\JsonContent(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: "results",
+                    type: "array",
+                    items: new OA\Items(ref: new Model(type: RoomCategory::class))
+                )
+            ]
+        )
+    )]
     public function getAll(RoomCategoryRepository $catRepo): Response
     {
         $catList = $catRepo->findAll();
@@ -24,7 +44,24 @@ class RoomCategoryController extends AbstractController
         return $this->json(["results" => $catList]);
     }
 
-    #[Route('/api/room/category/{id}', name: 'app_room_category')]
+    /**
+     * Get a room category by ID.
+     */
+    #[Route('/api/room/category/{id}', name: 'app_room_category', methods: ["GET"])]
+    #[OA\Tag(name: "Rooms")]
+    #[OA\Response(
+        response: 200,
+        description: 'Returns a room category',
+        content: new OA\JsonContent(
+            type: 'object',
+            ref: new Model(type: RoomCategory::class),
+        )
+    )]
+    #[OA\Parameter(
+        name: 'id',
+        in: 'path',
+        description: 'RoomCategory ID',
+    )]
     public function getById(RoomCategory $category): Response
     {
         return $this->json($category);

src/Controller/SearchRoomsController.php

@@ -5,15 +5,51 @@ namespace App\Controller;
 use App\Repository\FareTableRepository;
 use App\Repository\RoomAvailabilityRepository;
 use App\Repository\RoomCategoryRepository;
+use App\Request\SearchAvailabilityPeriodRequest;
+use App\Response\SearchAvailabilityResponse;
+use App\Request\SearchFareCategoryRequest;
+use App\Response\SearchFareCategoryResponse;
 use App\Service\PricesService;
+use Nelmio\ApiDocBundle\Annotation\Model;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\Routing\Attribute\Route;
+use OpenApi\Attributes as OA;
 
 class SearchRoomsController extends AbstractController
 {
-    #[Route('/api/search/availability', name: 'app_search_availability')]
+    /**
+     * Get availability for all rooms on period.
+     * For each room, the minimal availability will be returned.
+     */
+    #[Route('/api/search/availability', name: 'app_search_availability', methods: ["POST"])]
+    #[OA\Tag(name: "Searchs")]
+    #[OA\Response(
+        response: 200,
+        description: 'Each room available',
+        content: new OA\JsonContent(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: "results",
+                    type: "array",
+                    items: new OA\Items(ref: new Model(type: SearchAvailabilityResponse::class))
+                )
+            ]
+        )
+    )]
+    #[OA\RequestBody(
+        content: new OA\JsonContent(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: "filter",
+                    ref: new Model(type: SearchAvailabilityPeriodRequest::class),
+                ),
+            ],
+        )
+    )]
     public function getAvailabilityForPeriod(Request $request, RoomAvailabilityRepository $repoAvailability): Response
     {
         $payload = $request->toArray();
@@ -30,7 +66,12 @@ class SearchRoomsController extends AbstractController
         return $this->json(["results" => $rs]);
     }
 
-    #[Route('/api/search/availabilityDetails', name: 'app_search_availabilityDetails')]
+    /**
+     * Get Availability for all rooms on each day of a period.
+     * (Not used on Front-end APP)
+     */
+    #[Route('/api/search/availabilityDetails', name: 'app_search_availabilityDetails', methods: ["POST"])]
+    #[OA\Tag(name: "Searchs")]
     public function getAvailabilityForPeriodDetails(Request $request, RoomAvailabilityRepository $repoAvailability): Response
     {
         $payload = $request->toArray();
@@ -44,10 +85,41 @@ class SearchRoomsController extends AbstractController
 
         $rs = $repoAvailability->getAvailabilityForPeriodDetails($startDate, $endDate);
 
-        return $this->json($rs);
+        return $this->json(["results" => $rs]);
     }
 
-    #[Route('/api/search/fares', name: 'app_search_faresForCategory')]
+    /**
+     * Get room category price for given period.
+     * Returns price for a room category. 
+     * This price is the total for all the selected days by guest number.
+     */
+    #[Route('/api/search/fares', name: 'app_search_faresForCategory', methods: ["POST"])]
+    #[OA\Tag(name: "Searchs")]
+    #[OA\Response(
+        response: 200,
+        description: 'Room price by guest number',
+        content: new OA\JsonContent(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: "results",
+                    type: "array",
+                    items: new OA\Items(ref: new Model(type: SearchFareCategoryResponse::class))
+                )
+            ]
+        )
+    )]
+    #[OA\RequestBody(
+        content: new OA\JsonContent(
+            type: 'object',
+            properties: [
+                new OA\Property(
+                    property: "filter",
+                    ref: new Model(type: SearchFareCategoryRequest::class),
+                ),
+            ],
+        )
+    )]
     public function getFaresForCategoryOnPeriod(Request $request, RoomCategoryRepository $repoCat, PricesService $priceService): Response
     {
         $payload = $request->toArray();
@@ -73,13 +145,13 @@ class SearchRoomsController extends AbstractController
         $fareList = $priceService->getFinalPricesForSearch($roomCategory, $startDate, $endDate);
         $rs = [];
         foreach ($fareList as $key => $value) {
-            $rs[] = [ "guestNumber" => $key, "price" => $value];
+            $rs[] = ["guestNumber" => $key, "price" => $value];
         }
 
         return $this->json(["results" => $rs]);
     }
 
-    #[Route('/search/debug', name: 'app_search_faresDebug')]
+    #[Route('/debug/search', name: 'app_search_faresDebug')]
     public function faresDebug(Request $request, PricesService $priceService, FareTableRepository $repoFareTable, RoomCategoryRepository $repoCat): Response
     {
         $fareTable[] = $repoFareTable->find(1);

src/Request/BookingCreateRequest.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Request;
+
+use App\Entity\BookingCustomer;
+use OpenApi\Attributes as OA;
+
+class BookingCreateRequest
+{
+    #[OA\Property(description: 'Booking Arrival date')]
+    public \DateTime $arrivalDate;
+
+    #[OA\Property(description: 'Booking departure date')]
+    public \DateTime $departureDate;
+
+    #[OA\Property(
+        description: 'Booking customer details',
+    )]
+    public BookingCustomer $customerDetails;
+
+    /**
+     * @var array<BookingCreateRoomItem>
+     */
+    #[OA\Property(
+        description: 'Rooms to book',
+    )]
+    public array $rooms;
+}

src/Request/BookingCreateRoomItem.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace App\Request;
+
+use OpenApi\Attributes as OA;
+
+class BookingCreateRoomItem
+{
+    #[OA\Property(description: 'Room category ID')]
+    public string $roomCategory;
+
+    #[OA\Property(description: 'Guest number for the room')]
+    public int $guestNumber;
+
+    #[OA\Property(description: 'Room amount')]
+    public int $amount;
+}

src/Request/BookingDetailsRequest.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace App\Request;
+
+use OpenApi\Attributes as OA;
+
+class BookingDetailsRequest
+{
+    #[OA\Property(description: 'Booking reference number')]
+    public string $refNumber;
+
+    #[OA\Property(maxLength: 255, description: 'Email associated to the booking')]
+    public string $email;
+}

src/Request/SearchAvailabilityPeriodRequest.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace App\Request;
+
+use OpenApi\Attributes as OA;
+
+class SearchAvailabilityPeriodRequest
+{
+    #[OA\Property(description: 'Period start date')]
+    public \DateTime $startDate;
+
+    #[OA\Property(description: 'Period end date')]
+    public \DateTime $endDate;
+}

src/Request/SearchFareCategoryRequest.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace App\Request;
+
+use OpenApi\Attributes as OA;
+
+class SearchFareCategoryRequest
+{
+    #[OA\Property(description: 'Room category ID')]
+    public int $roomCategory;
+
+    #[OA\Property(description: 'Period start date')]
+    public \DateTime $startDate;
+
+    #[OA\Property(description: 'Period end date')]
+    public \DateTime $endDate;
+}

src/Response/BookingCreateResponse.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace App\Response;
+
+use OpenApi\Attributes as OA;
+
+class BookingCreateResponse
+{
+    #[OA\Property(description: 'Booking reference number')]
+    public string $refNumber;
+}

src/Response/SearchAvailabilityResponse.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace App\Response;
+
+use OpenApi\Attributes as OA;
+
+class SearchAvailabilityResponse
+{
+    #[OA\Property(description: 'Room category ID')]
+    public string $roomCategory;
+
+    #[OA\Property(description: 'Number of available rooms')]
+    public int $availability;
+}

src/Response/SearchFareCategoryResponse.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace App\Response;
+
+use OpenApi\Attributes as OA;
+
+class SearchFareCategoryResponse
+{
+    #[OA\Property(description: 'Number of guests')]
+    public int $guestNumber;
+
+    #[OA\Property(description: 'room price')]
+    public int $price;
+}

symfony.lock

@@ -35,6 +35,19 @@
             "ref": "b131e6cbfe1b898a508987851963fff485986285"
         }
     },
+    "nelmio/api-doc-bundle": {
+        "version": "4.30",
+        "recipe": {
+            "repo": "github.com/symfony/recipes-contrib",
+            "branch": "main",
+            "version": "3.0",
+            "ref": "c8e0c38e1a280ab9e37587a8fa32b251d5bc1c94"
+        },
+        "files": [
+            "./config/packages/nelmio_api_doc.yaml",
+            "./config/routes/nelmio_api_doc.yaml"
+        ]
+    },
     "nelmio/cors-bundle": {
         "version": "2.4",
         "recipe": {