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

Author: Turbo87

src/controllers/user/session.rs

@@ -19,7 +19,7 @@ use crate::util::errors::{bad_request, server_error, AppResult};
 use crate::views::EncodableMe;
 use crates_io_github::GithubUser;
 
-/// Handles the `GET /api/private/session/begin` route.
+/// Begin authentication flow.
 ///
 /// This route will return an authorization URL for the GitHub OAuth flow including the crates.io
 /// `client_id` and a randomly generated `state` secret.
@@ -34,6 +34,13 @@ use crates_io_github::GithubUser;
 ///     "url": "https://github.com/login/oauth/authorize?client_id=...&state=...&scope=read%3Aorg"
 /// }
 /// ```
+#[utoipa::path(
+    get,
+    path = "/api/private/session/begin",
+    operation_id = "begin_session",
+    tag = "session",
+    responses((status = 200, description = "Successful Response")),
+)]
 pub async fn begin(app: AppState, session: SessionExtension) -> ErasedJson {
     let (url, state) = app
         .github_oauth

src/router.rs

@@ -60,11 +60,11 @@ pub fn build_axum_router(state: AppState) -> Router<()> {
         .routes(routes!(user::me::confirm_user_email))
         .routes(routes!(user::resend::regenerate_token_and_send))
         .routes(routes!(site_metadata::show_deployed_sha))
+        // Session management
+        .routes(routes!(user::session::begin))
         .split_for_parts();
 
     let mut router = router
-        // Session management
-        .route("/api/private/session/begin", get(user::session::begin))
         .route(
             "/api/private/session/authorize",
             get(user::session::authorize),

src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap

@@ -20,6 +20,21 @@ snapshot_kind: text
   },
   "openapi": "3.1.0",
   "paths": {
+    "/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```",
+        "operationId": "begin_session",
+        "responses": {
+          "200": {
+            "description": "Successful Response"
+          }
+        },
+        "summary": "Begin authentication flow.",
+        "tags": [
+          "session"
+        ]
+      }
+    },
     "/api/v1/categories": {
       "get": {
         "operationId": "list_categories",