Add purchase product errors docs

hopper/api/views.py

@@ -17,7 +17,12 @@ from hopper.api.dto import (
 )
 from hopper.engine import GameEngine
 from hopper.enums import Direction, PlayerMoveResult
-from hopper.errors import Collision, GameLockForMovement, PositionOutOfBounds, PurchaseForbiddenForPlayer
+from hopper.errors import (
+    Collision,
+    GameLockForMovement,
+    PositionOutOfBounds,
+    PurchaseForbiddenForPlayer,
+)
 from hopper.models.player import Player
 from settings import settings
 
@@ -167,7 +172,24 @@ async def get_product(id: str) -> ProductDto:
     )
 
 
-@router.post("/player/{id}/product/purchase", response_model=ProductDto)
+@router.post(
+    "/player/{id}/product/purchase",
+    response_model=ProductDto,
+    responses={
+        status.HTTP_200_OK: {
+            "model": ProductDto,
+            "description": "Product purchased",
+        },
+        status.HTTP_403_FORBIDDEN: {
+            "model": ErrorResponseDto,
+            "description": "Purchase forbidden for this player",
+        },
+        status.HTTP_404_NOT_FOUND: {
+            "model": ErrorResponseDto,
+            "description": " Player with id not found, probably kicked out",
+        },
+    },
+)
 async def purchase_product(
     body: PurchaseProductDto,
     engine: GameEngine = Depends(get_game_engine),