Add OpenAPI documentation for GET /api/v1/crates/{name}/{version}/downloads response payload

Author: Turbo87

src/controllers/version/downloads.rs

@@ -9,10 +9,10 @@ use crate::schema::*;
 use crate::util::errors::AppResult;
 use crate::util::{RequestUtils, redirect};
 use crate::views::EncodableVersionDownload;
+use axum::Json;
 use axum::extract::{FromRequestParts, Query};
 use axum::response::{IntoResponse, Response};
 use axum_extra::json;
-use axum_extra::response::ErasedJson;
 use chrono::{Duration, NaiveDate, Utc};
 use diesel::prelude::*;
 use diesel_async::RunQueryDsl;
@@ -51,6 +51,11 @@ pub struct DownloadsQueryParams {
     before_date: Option<NaiveDate>,
 }
 
+#[derive(Debug, Serialize, utoipa::ToSchema)]
+pub struct DownloadsResponse {
+    pub version_downloads: Vec<EncodableVersionDownload>,
+}
+
 /// Get the download counts for a crate version.
 ///
 /// This includes the per-day downloads for the last 90 days.
@@ -59,13 +64,13 @@ pub struct DownloadsQueryParams {
     path = "/api/v1/crates/{name}/{version}/downloads",
     params(CrateVersionPath, DownloadsQueryParams),
     tag = "versions",
-    responses((status = 200, description = "Successful Response")),
+    responses((status = 200, description = "Successful Response", body = inline(DownloadsResponse))),
 )]
 pub async fn get_version_downloads(
     app: AppState,
     path: CrateVersionPath,
     params: DownloadsQueryParams,
-) -> AppResult<ErasedJson> {
+) -> AppResult<Json<DownloadsResponse>> {
     let mut conn = app.db_read().await?;
     let version = path.load_version(&mut conn).await?;
 
@@ -75,14 +80,14 @@ pub async fn get_version_downloads(
 
     let cutoff_start_date = cutoff_end_date - Duration::days(89);
 
-    let downloads = VersionDownload::belonging_to(&version)
+    let version_downloads = VersionDownload::belonging_to(&version)
         .filter(version_downloads::date.between(cutoff_start_date, cutoff_end_date))
         .order(version_downloads::date)
         .load(&mut conn)
         .await?
         .into_iter()
         .map(VersionDownload::into)
-        .collect::<Vec<EncodableVersionDownload>>();
+        .collect();
 
-    Ok(json!({ "version_downloads": downloads }))
+    Ok(Json(DownloadsResponse { version_downloads }))
 }

src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap

@@ -645,6 +645,33 @@ expression: response.json()
         ],
         "type": "object"
       },
+      "VersionDownload": {
+        "properties": {
+          "date": {
+            "description": "The date this download count is for.",
+            "example": "2019-12-13",
+            "type": "string"
+          },
+          "downloads": {
+            "description": "The number of downloads for this version on the given date.",
+            "example": 123,
+            "format": "int32",
+            "type": "integer"
+          },
+          "version": {
+            "description": "The ID of the version this download count is for.",
+            "example": 42,
+            "format": "int32",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "version",
+          "downloads",
+          "date"
+        ],
+        "type": "object"
+      },
       "VersionLinks": {
         "properties": {
           "authors": {
@@ -2011,6 +2038,24 @@ expression: response.json()
         ],
         "responses": {
           "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "version_downloads": {
+                      "items": {
+                        "$ref": "#/components/schemas/VersionDownload"
+                      },
+                      "type": "array"
+                    }
+                  },
+                  "required": [
+                    "version_downloads"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
             "description": "Successful Response"
           }
         },

src/views.rs

@@ -201,10 +201,19 @@ impl EncodableDependency {
     }
 }
 
-#[derive(Serialize, Deserialize, Debug)]
+#[derive(Serialize, Deserialize, Debug, utoipa::ToSchema)]
+#[schema(as = VersionDownload)]
 pub struct EncodableVersionDownload {
+    /// The ID of the version this download count is for.
+    #[schema(example = 42)]
     pub version: i32,
+
+    /// The number of downloads for this version on the given date.
+    #[schema(example = 123)]
     pub downloads: i32,
+
+    /// The date this download count is for.
+    #[schema(example = "2019-12-13")]
     pub date: String,
 }