diff --git a/backend/main.py b/backend/main.py index de5d4dc..3b99212 100644 --- a/backend/main.py +++ b/backend/main.py @@ -55,6 +55,7 @@ from event_signups import ( get_event_responses, ) + class Login(BaseModel): username: str password: str @@ -117,9 +118,14 @@ app.add_middleware( allow_headers=["*"], ) + # generaal -@app.get("/") +@app.get( + "/", + summary="API status", + description="Returns the current status of the Calendar API.", +) def home(): return { "status": "online", @@ -127,7 +133,11 @@ def home(): } -@app.get("/database") +@app.get( + "/database", + summary="Get database status", + description="Returns the names of all tables currently available in the database.", +) def database_status( user_id: int = Depends(get_current_user), ): @@ -140,7 +150,11 @@ def database_status( # users -@app.post("/create-user") +@app.post( + "/create-user", + summary="Create a user", + description="Creates a new user account. The username must be unique.", +) def api_create_user(user: UserCreate): try: user_id = create_user( @@ -160,7 +174,11 @@ def api_create_user(user: UserCreate): } -@app.post("/login") +@app.post( + "/login", + summary="Log in", + description="Authenticates a user and returns a JWT access token.", +) def api_login(login: Login): user_id = verify_user( login.username, @@ -181,7 +199,11 @@ def api_login(login: Login): } -@app.get("/me") +@app.get( + "/me", + summary="Get current user", + description="Returns the profile of the currently authenticated user.", +) def get_me( user_id: int = Depends(get_current_user), ): @@ -196,7 +218,11 @@ def get_me( return dict(user) -@app.get("/users/{user_id}") +@app.get( + "/users/{user_id}", + summary="Get a user", + description="Returns the profile of a user by their user ID.", +) def api_get_user( user_id: int, current_user: int = Depends(get_current_user), @@ -211,7 +237,14 @@ def api_get_user( return dict(user) -@app.post("/create-room") + +# rooms + +@app.post( + "/create-room", + summary="Create a room", + description="Creates a new room and makes the authenticated user its owner.", +) def api_create_room( room: RoomCreate, user_id: int = Depends(get_current_user), @@ -235,7 +268,11 @@ def api_create_room( } -@app.post("/search-room") +@app.post( + "/search-room", + summary="Search for a room", + description="Searches for a room using its invite code.", +) def api_search_room( room: RoomSearch, user_id: int = Depends(get_current_user), @@ -256,7 +293,11 @@ def api_search_room( } -@app.post("/join-room") +@app.post( + "/join-room", + summary="Join a room", + description="Joins the authenticated user to a room using its invite code.", +) def api_join_room( room: RoomJoin, user_id: int = Depends(get_current_user), @@ -278,7 +319,11 @@ def api_join_room( } -@app.get("/rooms") +@app.get( + "/rooms", + summary="Get user's rooms", + description="Returns all rooms the authenticated user is a member of.", +) def api_get_rooms( user_id: int = Depends(get_current_user), ): @@ -289,7 +334,11 @@ def api_get_rooms( } -@app.get("/rooms/{room_id}") +@app.get( + "/rooms/{room_id}", + summary="Get a room", + description="Returns information about a room. The authenticated user must be a member.", +) def api_get_room( room_id: int, user_id: int = Depends(get_current_user), @@ -314,7 +363,11 @@ def api_get_room( return dict(room) -@app.get("/rooms/{room_id}/whoami") +@app.get( + "/rooms/{room_id}/whoami", + summary="Get current user's room role", + description="Returns the authenticated user's role and permissions within a room.", +) def api_room_whoami( room_id: int, user_id: int = Depends(get_current_user), @@ -334,7 +387,11 @@ def api_room_whoami( } -@app.get("/rooms/{room_id}/members") +@app.get( + "/rooms/{room_id}/members", + summary="Get room members", + description="Returns all members of a room. The authenticated user must be a member.", +) def api_room_members( room_id: int, user_id: int = Depends(get_current_user), @@ -352,7 +409,11 @@ def api_room_members( } -@app.delete("/rooms/{room_id}/members/me") +@app.delete( + "/rooms/{room_id}/members/me", + summary="Leave a room", + description="Removes the authenticated user from a room.", +) def api_leave_room( room_id: int, user_id: int = Depends(get_current_user), @@ -372,7 +433,18 @@ def api_leave_room( "status": "left", } -@app.delete("/rooms/{room_id}/members/{user_id}") + +@app.delete( + "/rooms/{room_id}/members/{user_id}", + summary="Remove a room member", + description=""" +Removes a member from a room. + +Admins can remove members with a lower role. +Owners can remove members and admins. +A user cannot remove someone with an equal or higher role. +""", +) def api_remove_member( room_id: int, user_id: int, @@ -412,9 +484,14 @@ def api_remove_member( "user_id": user_id, } -# some settings -@app.patch("/rooms/{room_id}") +# room settings + +@app.patch( + "/rooms/{room_id}", + summary="Rename a room", + description="Changes the name of a room. Requires admin or owner permissions.", +) def update_room( room_id: int, data: RoomUpdate, @@ -433,7 +510,11 @@ def update_room( ) -@app.post("/rooms/{room_id}/invite-code") +@app.post( + "/rooms/{room_id}/invite-code", + summary="Regenerate invite code", + description="Generates a new invite code for a room. Requires admin or owner permissions.", +) def update_invite_code( room_id: int, user_id: int = Depends(get_current_user), @@ -447,7 +528,11 @@ def update_invite_code( return regenerate_invite_code(room_id) -@app.delete("/rooms/{room_id}") +@app.delete( + "/rooms/{room_id}", + summary="Delete a room", + description="Permanently deletes a room. Only the room owner can perform this action.", +) def delete_room( room_id: int, user_id: int = Depends(get_current_user), @@ -463,7 +548,11 @@ def delete_room( # events -@app.get("/rooms/{room_id}/events") +@app.get( + "/rooms/{room_id}/events", + summary="Get room events", + description="Returns all events belonging to a room. The authenticated user must be a member.", +) def api_room_events( room_id: int, user_id: int = Depends(get_current_user), @@ -481,7 +570,11 @@ def api_room_events( } -@app.post("/events") +@app.post( + "/events", + summary="Create an event", + description="Creates a new event in a room. The authenticated user must be a member of the room.", +) def api_create_event( event: EventCreate, user_id: int = Depends(get_current_user), @@ -511,7 +604,11 @@ def api_create_event( } -@app.get("/events") +@app.get( + "/events", + summary="Get user's events", + description="Returns events from rooms the authenticated user belongs to.", +) def get_events( user_id: int = Depends(get_current_user), ): @@ -522,7 +619,11 @@ def get_events( } -@app.get("/events/{event_id}") +@app.get( + "/events/{event_id}", + summary="Get an event", + description="Returns a specific event. The authenticated user must be a member of its room.", +) def api_get_event( event_id: int, user_id: int = Depends(get_current_user), @@ -548,7 +649,11 @@ def api_get_event( return dict(event) -@app.post("/events/{event_id}/respond") +@app.post( + "/events/{event_id}/respond", + summary="Respond to an event", + description="Saves the authenticated user's response to an event and checks whether the event reached its confirmation threshold.", +) def respond_event( event_id: int, status: Literal[ @@ -590,7 +695,11 @@ def respond_event( } -@app.get("/events/{event_id}/responses") +@app.get( + "/events/{event_id}/responses", + summary="Get event responses", + description="Returns all responses submitted by members for an event.", +) def api_event_responses( event_id: int, user_id: int = Depends(get_current_user), @@ -622,7 +731,12 @@ def api_event_responses( ], } -@app.patch("/events/{event_id}") + +@app.patch( + "/events/{event_id}", + summary="Update an event", + description="Updates an event. The event creator or a room admin can perform this action.", +) def api_update_event( event_id: int, event: EventUpdate, @@ -664,7 +778,11 @@ def api_update_event( } -@app.delete("/events/{event_id}") +@app.delete( + "/events/{event_id}", + summary="Delete an event", + description="Deletes an event. The event creator or a room admin can perform this action.", +) def api_delete_event( event_id: int, user_id: int = Depends(get_current_user), @@ -697,23 +815,20 @@ def api_delete_event( "status": "deleted", } -#easter egg + +# easter egg @app.get( "/ascii-art", + summary="Display ASCII art", + description="Returns the Calendar API ASCII art as plain text.", response_class=PlainTextResponse, ) def ascii_art(): - return """ - ██████╗ █████╗ ██╗ ███████╗███╗ ██╗██████╗ █████╗ ██████╗ - ██╔════╝██╔══██╗██║ ██╔════╝████╗ ██║██╔══██╗██╔══██╗██╔══██╗ - ██║ ███████║██║ █████╗ ██╔██╗ ██║██║ ██║███████║██████╔╝ - ██║ ██╔══██║██║ ██╔══╝ ██║╚██╗██║██║ ██║██╔══██║██╔══██╗ - ╚██████╗██║ ██║███████╗███████╗██║ ╚████║██████╔╝██║ ██║██║ ██║ - ╚═════╝╚═╝ ╚═╝╚══════╝╚══════╝╚═╝ ╚═══╝╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ - - status: online - - "You are a stinky Poo" - - Ben de Roo, programmer - """ \ No newline at end of file + return """ __ .__ __ + ___.__. ____ __ __ _____ _______ ____ _____ _______/ |_|__| ____ | | _____.__. ______ ____ ____ +< | |/ _ \| | \ \__ \\\\_ __ \_/ __ \ \__ \ / ___/\ __\ |/ \| |/ < | | \____ \ / _ \ / _ \ + \___ ( <_> ) | / / __ \| | \/\ ___/ / __ \_ \___ \ | | | | | \ < \___ | | |_> > <_> | <_> ) + / ____|\____/|____/ (____ /__| \___ > (____ / /____ > |__| |__|___| /__|_ \/ ____| | __/ \____/ \____/ + \/ \/ \/ \/ \/ \/ \/\/ |__| + """ \ No newline at end of file