utoipa: Add annotations to /private/session/authorize endpoints

Author: Turbo87

src/controllers/user/session.rs

@@ -61,7 +61,7 @@ pub struct AuthorizeQuery {
     state: CsrfToken,
 }
 
-/// Handles the `GET /api/private/session/authorize` route.
+/// Complete authentication flow.
 ///
 /// This route is called from the GitHub API OAuth flow after the user accepted or rejected
 /// the data access permissions. It will check the `state` parameter and then call the GitHub API
@@ -79,7 +79,6 @@ pub struct AuthorizeQuery {
 ///
 /// ```json
 /// {
-///     "api_token": "b84a63c4ea3fcb4ac84",
 ///     "user": {
 ///         "email": "[email protected]",
 ///         "name": "Foo Bar",
@@ -89,6 +88,13 @@ pub struct AuthorizeQuery {
 ///     }
 /// }
 /// ```
+#[utoipa::path(
+    get,
+    path = "/api/private/session/authorize",
+    operation_id = "authorize_session",
+    tag = "session",
+    responses((status = 200, description = "Successful Response")),
+)]
 pub async fn authorize(
     query: AuthorizeQuery,
     app: AppState,

src/router.rs

@@ -62,13 +62,10 @@ pub fn build_axum_router(state: AppState) -> Router<()> {
         .routes(routes!(site_metadata::show_deployed_sha))
         // Session management
         .routes(routes!(user::session::begin))
+        .routes(routes!(user::session::authorize))
         .split_for_parts();
 
     let mut router = router
-        .route(
-            "/api/private/session/authorize",
-            get(user::session::authorize),
-        )
         .route("/api/private/session", delete(user::session::logout))
         // Metrics
         .route("/api/private/metrics/:kind", get(metrics::prometheus))

src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap

@@ -20,6 +20,21 @@ snapshot_kind: text
   },
   "openapi": "3.1.0",
   "paths": {
+    "/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\": \"[email protected]\",\n        \"name\": \"Foo Bar\",\n        \"login\": \"foobar\",\n        \"avatar\": \"https://avatars.githubusercontent.com/u/1234\",\n        \"url\": null\n    }\n}\n```",
+        "operationId": "authorize_session",
+        "responses": {
+          "200": {
+            "description": "Successful Response"
+          }
+        },
+        "summary": "Complete authentication flow.",
+        "tags": [
+          "session"
+        ]
+      }
+    },
     "/api/private/session/begin": {
       "get": {
         "description": "This route will return an authorization URL for the GitHub OAuth flow including the crates.io\n`client_id` and a randomly generated `state` secret.\n\nsee <https://developer.github.com/v3/oauth/#redirect-users-to-request-github-access>\n\n## Response Body Example\n\n```json\n{\n    \"state\": \"b84a63c4ea3fcb4ac84\",\n    \"url\": \"https://github.com/login/oauth/authorize?client_id=...&state=...&scope=read%3Aorg\"\n}\n```",