Added OpenAPI docs using nelmioAPIDocBundle.

2024-09-20 21:29:23 +02:00
parent 0cf6f231a3
commit bfcd04c701
18 changed files with 610 additions and 20 deletions
@@ -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",
@@ -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": [
@@ -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],
 ];
@@ -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
@@ -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 }
@@ -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, 
-                        "No se puedo obtener el precio para la categoría: " . $roommCategory->getId() . " , guests: " . $selecctedGuestAmount);
+                    throw new HttpException(
+                        500,
+                        "No se puedo obtener el precio para la categoría: " . $roomCategory->getId() . " , guests: " . $selectedGuestAmount
+                    );
                }

                $entityManager->persist($room);
@@ -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);
@@ -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 Symfony\Component\Serializer\Context\Normalizer\ObjectNormalizerContextBuilder;
+use OpenApi\Attributes as OA;
+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);
@@ -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);
@@ -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;
+}
@@ -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;
+}
@@ -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;
+}
@@ -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;
+}
@@ -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;
+}
@@ -0,0 +1,11 @@
+<?php
+
+namespace App\Response;
+
+use OpenApi\Attributes as OA;
+
+class BookingCreateResponse
+{
+    #[OA\Property(description: 'Booking reference number')]
+    public string $refNumber;
+}
@@ -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;
+}
@@ -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;
+}
@@ -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": {