Improve OpenAPI documentation for GET /api/v1/crates/{name}/reverse_dependencies endpoints

Author: Turbo87

src/controllers/krate/rev_deps.rs

@@ -4,26 +4,43 @@ use crate::controllers::krate::CratePath;
 use crate::models::{CrateName, User, Version, VersionOwnerAction};
 use crate::util::errors::AppResult;
 use crate::views::{EncodableDependency, EncodableVersion};
-use axum_extra::json;
-use axum_extra::response::ErasedJson;
+use axum::Json;
 use crates_io_database::schema::{crates, users, versions};
 use diesel::prelude::*;
 use diesel_async::RunQueryDsl;
 use http::request::Parts;
 
+#[derive(Debug, Serialize, utoipa::ToSchema)]
+pub struct RevDepsResponse {
+    /// The list of reverse dependencies of the crate.
+    dependencies: Vec<EncodableDependency>,
+
+    /// The versions referenced in the `dependencies` field.
+    versions: Vec<EncodableVersion>,
+
+    #[schema(inline)]
+    meta: RevDepsMeta,
+}
+
+#[derive(Debug, Serialize, utoipa::ToSchema)]
+pub struct RevDepsMeta {
+    #[schema(example = 32)]
+    total: i64,
+}
+
 /// List reverse dependencies of a crate.
 #[utoipa::path(
     get,
     path = "/api/v1/crates/{name}/reverse_dependencies",
     params(CratePath),
     tag = "crates",
-    responses((status = 200, description = "Successful Response")),
+    responses((status = 200, description = "Successful Response", body = inline(RevDepsResponse))),
 )]
 pub async fn list_reverse_dependencies(
     app: AppState,
     path: CratePath,
     req: Parts,
-) -> AppResult<ErasedJson> {
+) -> AppResult<Json<RevDepsResponse>> {
     let mut conn = app.db_read().await?;
 
     let pagination_options = PaginationOptions::builder().gather(&req)?;
@@ -64,9 +81,9 @@ pub async fn list_reverse_dependencies(
         })
         .collect::<Vec<_>>();
 
-    Ok(json!({
-        "dependencies": rev_deps,
-        "versions": versions,
-        "meta": { "total": total },
+    Ok(Json(RevDepsResponse {
+        dependencies: rev_deps,
+        versions,
+        meta: RevDepsMeta { total },
     }))
 }

src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap

@@ -2288,6 +2288,47 @@ expression: response.json()
         ],
         "responses": {
           "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "dependencies": {
+                      "description": "The list of reverse dependencies of the crate.",
+                      "items": {
+                        "$ref": "#/components/schemas/EncodableDependency"
+                      },
+                      "type": "array"
+                    },
+                    "meta": {
+                      "properties": {
+                        "total": {
+                          "example": 32,
+                          "format": "int64",
+                          "type": "integer"
+                        }
+                      },
+                      "required": [
+                        "total"
+                      ],
+                      "type": "object"
+                    },
+                    "versions": {
+                      "description": "The versions referenced in the `dependencies` field.",
+                      "items": {
+                        "$ref": "#/components/schemas/Version"
+                      },
+                      "type": "array"
+                    }
+                  },
+                  "required": [
+                    "dependencies",
+                    "versions",
+                    "meta"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
             "description": "Successful Response"
           }
         },