From 1826d06de595d5f48e33695273f77e5c300c80ad Mon Sep 17 00:00:00 2001
From: Tobias Bieniek <tobias@bieniek.cloud>
Date: Fri, 13 Dec 2024 18:36:22 +0100
Subject: [PATCH] utoipa: Add annotations to `/private/session` endpoints

---
 src/controllers/user/session.rs                    |  9 ++++++++-
 src/router.rs                                      |  2 +-
 ...rates_io__openapi__tests__openapi_snapshot.snap | 14 ++++++++++++++
 3 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/src/controllers/user/session.rs b/src/controllers/user/session.rs
index 3bd20c633c..84566e701a 100644
--- a/src/controllers/user/session.rs
+++ b/src/controllers/user/session.rs
@@ -171,7 +171,14 @@ async fn find_user_by_gh_id(conn: &mut AsyncPgConnection, gh_id: i32) -> QueryRe
         .optional()
 }
 
-/// Handles the `DELETE /api/private/session` route.
+/// End the current session.
+#[utoipa::path(
+    delete,
+    path = "/api/private/session",
+    operation_id = "end_session",
+    tag = "session",
+    responses((status = 200, description = "Successful Response")),
+)]
 pub async fn logout(session: SessionExtension) -> Json<bool> {
     session.remove("user_id");
     Json(true)
diff --git a/src/router.rs b/src/router.rs
index ccc164cb0f..9559e3ea0f 100644
--- a/src/router.rs
+++ b/src/router.rs
@@ -63,10 +63,10 @@ pub fn build_axum_router(state: AppState) -> Router<()> {
         // Session management
         .routes(routes!(user::session::begin))
         .routes(routes!(user::session::authorize))
+        .routes(routes!(user::session::logout))
         .split_for_parts();
 
     let mut router = router
-        .route("/api/private/session", delete(user::session::logout))
         // Metrics
         .route("/api/private/metrics/:kind", get(metrics::prometheus))
         // Crate ownership invitations management in the frontend
diff --git a/src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap b/src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap
index 6ec3ed289c..ca288d969e 100644
--- a/src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap
+++ b/src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap
@@ -20,6 +20,20 @@ snapshot_kind: text
   },
   "openapi": "3.1.0",
   "paths": {
+    "/api/private/session": {
+      "delete": {
+        "operationId": "end_session",
+        "responses": {
+          "200": {
+            "description": "Successful Response"
+          }
+        },
+        "summary": "End the current session.",
+        "tags": [
+          "session"
+        ]
+      }
+    },
     "/api/private/session/authorize": {
       "get": {
         "description": "This route is called from the GitHub API OAuth flow after the user accepted or rejected\nthe data access permissions. It will check the `state` parameter and then call the GitHub API\nto exchange the temporary `code` for an API token. The API token is returned together with\nthe corresponding user information.\n\nsee <https://developer.github.com/v3/oauth/#github-redirects-back-to-your-site>\n\n## Query Parameters\n\n- `code` – temporary code received from the GitHub API  **(Required)**\n- `state` – state parameter received from the GitHub API  **(Required)**\n\n## Response Body Example\n\n```json\n{\n    \"user\": {\n        \"email\": \"foo@bar.org\",\n        \"name\": \"Foo Bar\",\n        \"login\": \"foobar\",\n        \"avatar\": \"https://avatars.githubusercontent.com/u/1234\",\n        \"url\": null\n    }\n}\n```",