controllers/krate/search: Use utoipa annotations

Author: Turbo87

src/controllers/krate/search.rs

@@ -24,28 +24,35 @@ use crate::models::krate::ALL_COLUMNS;
 use crate::sql::{array_agg, canon_crate_name, lower};
 use crate::util::RequestUtils;
 
-/// Handles the `GET /crates` route.
-/// Returns a list of crates. Called in a variety of scenarios in the
-/// front end, including:
+/// Returns a list of crates.
+///
+/// Called in a variety of scenarios in the front end, including:
 /// - Alphabetical listing of crates
 /// - List of crates under a specific owner
 /// - Listing a user's followed crates
-///
-/// Notes:
-/// The different use cases this function covers is handled through passing
-/// in parameters in the GET request.
-///
-/// We would like to stop adding functionality in here. It was built like
-/// this to keep the number of database queries low, though given Rust's
-/// low performance overhead, this is a soft goal to have, and can afford
-/// more database transactions if it aids understandability.
-///
-/// All of the edge cases for this function are not currently covered
-/// in testing, and if they fail, it is difficult to determine what
-/// caused the break. In the future, we should look at splitting this
-/// function out to cover the different use cases, and create unit tests
-/// for them.
+#[utoipa::path(
+    get,
+    path = "/api/v1/crates",
+    operation_id = "crates_list",
+    tag = "crates",
+    responses((status = 200, description = "Successful Response")),
+)]
 pub async fn search(app: AppState, req: Parts) -> AppResult<ErasedJson> {
+    // Notes:
+    // The different use cases this function covers is handled through passing
+    // in parameters in the GET request.
+    //
+    // We would like to stop adding functionality in here. It was built like
+    // this to keep the number of database queries low, though given Rust's
+    // low performance overhead, this is a soft goal to have, and can afford
+    // more database transactions if it aids understandability.
+    //
+    // All of the edge cases for this function are not currently covered
+    // in testing, and if they fail, it is difficult to determine what
+    // caused the break. In the future, we should look at splitting this
+    // function out to cover the different use cases, and create unit tests
+    // for them.
+
     let mut conn = app.db_read().await?;
 
     use diesel::sql_types::Float;

src/router.rs

@@ -3,6 +3,7 @@ use axum::response::IntoResponse;
 use axum::routing::{delete, get, post, put};
 use axum::Router;
 use http::{Method, StatusCode};
+use utoipa_axum::routes;
 use utoipa_swagger_ui::SwaggerUi;
 
 use crate::app::AppState;
@@ -15,11 +16,14 @@ use crate::Env;
 const MAX_PUBLISH_CONTENT_LENGTH: usize = 128 * 1024 * 1024; // 128 MB
 
 pub fn build_axum_router(state: AppState) -> Router<()> {
-    let (router, openapi) = BaseOpenApi::router().split_for_parts();
+    let (router, openapi) = BaseOpenApi::router()
+        .routes(routes!(
+            // Route used by both `cargo search` and the frontend
+            krate::search::search
+        ))
+        .split_for_parts();
 
     let mut router = router
-        // Route used by both `cargo search` and the frontend
-        .route("/api/v1/crates", get(krate::search::search))
         // Routes used by `cargo`
         .route(
             "/api/v1/crates/new",

src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap

@@ -19,7 +19,23 @@ snapshot_kind: text
     "version": "0.0.0"
   },
   "openapi": "3.1.0",
-  "paths": {},
+  "paths": {
+    "/api/v1/crates": {
+      "get": {
+        "description": "Called in a variety of scenarios in the front end, including:\n- Alphabetical listing of crates\n- List of crates under a specific owner\n- Listing a user's followed crates",
+        "operationId": "crates_list",
+        "responses": {
+          "200": {
+            "description": "Successful Response"
+          }
+        },
+        "summary": "Returns a list of crates.",
+        "tags": [
+          "crates"
+        ]
+      }
+    }
+  },
   "servers": [
     {
       "url": "https://crates.io"