Skip to content

Commit 0a5c9e7

Browse files
committed
Add OpenAPI documentation for GET /api/v1/crates/{name}/{version}/downloads response payload
1 parent 40ec540 commit 0a5c9e7

File tree

3 files changed

+66
-7
lines changed

3 files changed

+66
-7
lines changed

src/controllers/version/downloads.rs

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,10 @@ use crate::schema::*;
99
use crate::util::errors::AppResult;
1010
use crate::util::{RequestUtils, redirect};
1111
use crate::views::EncodableVersionDownload;
12+
use axum::Json;
1213
use axum::extract::{FromRequestParts, Query};
1314
use axum::response::{IntoResponse, Response};
1415
use axum_extra::json;
15-
use axum_extra::response::ErasedJson;
1616
use chrono::{Duration, NaiveDate, Utc};
1717
use diesel::prelude::*;
1818
use diesel_async::RunQueryDsl;
@@ -51,6 +51,11 @@ pub struct DownloadsQueryParams {
5151
before_date: Option<NaiveDate>,
5252
}
5353

54+
#[derive(Debug, Serialize, utoipa::ToSchema)]
55+
pub struct DownloadsResponse {
56+
pub version_downloads: Vec<EncodableVersionDownload>,
57+
}
58+
5459
/// Get the download counts for a crate version.
5560
///
5661
/// This includes the per-day downloads for the last 90 days.
@@ -59,13 +64,13 @@ pub struct DownloadsQueryParams {
5964
path = "/api/v1/crates/{name}/{version}/downloads",
6065
params(CrateVersionPath, DownloadsQueryParams),
6166
tag = "versions",
62-
responses((status = 200, description = "Successful Response")),
67+
responses((status = 200, description = "Successful Response", body = inline(DownloadsResponse))),
6368
)]
6469
pub async fn get_version_downloads(
6570
app: AppState,
6671
path: CrateVersionPath,
6772
params: DownloadsQueryParams,
68-
) -> AppResult<ErasedJson> {
73+
) -> AppResult<Json<DownloadsResponse>> {
6974
let mut conn = app.db_read().await?;
7075
let version = path.load_version(&mut conn).await?;
7176

@@ -75,14 +80,14 @@ pub async fn get_version_downloads(
7580

7681
let cutoff_start_date = cutoff_end_date - Duration::days(89);
7782

78-
let downloads = VersionDownload::belonging_to(&version)
83+
let version_downloads = VersionDownload::belonging_to(&version)
7984
.filter(version_downloads::date.between(cutoff_start_date, cutoff_end_date))
8085
.order(version_downloads::date)
8186
.load(&mut conn)
8287
.await?
8388
.into_iter()
8489
.map(VersionDownload::into)
85-
.collect::<Vec<EncodableVersionDownload>>();
90+
.collect();
8691

87-
Ok(json!({ "version_downloads": downloads }))
92+
Ok(Json(DownloadsResponse { version_downloads }))
8893
}

src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -645,6 +645,33 @@ expression: response.json()
645645
],
646646
"type": "object"
647647
},
648+
"VersionDownload": {
649+
"properties": {
650+
"date": {
651+
"description": "The date this download count is for.",
652+
"example": "2019-12-13",
653+
"type": "string"
654+
},
655+
"downloads": {
656+
"description": "The number of downloads for this version on the given date.",
657+
"example": 123,
658+
"format": "int32",
659+
"type": "integer"
660+
},
661+
"version": {
662+
"description": "The ID of the version this download count is for.",
663+
"example": 42,
664+
"format": "int32",
665+
"type": "integer"
666+
}
667+
},
668+
"required": [
669+
"version",
670+
"downloads",
671+
"date"
672+
],
673+
"type": "object"
674+
},
648675
"VersionLinks": {
649676
"properties": {
650677
"authors": {
@@ -2011,6 +2038,24 @@ expression: response.json()
20112038
],
20122039
"responses": {
20132040
"200": {
2041+
"content": {
2042+
"application/json": {
2043+
"schema": {
2044+
"properties": {
2045+
"version_downloads": {
2046+
"items": {
2047+
"$ref": "#/components/schemas/VersionDownload"
2048+
},
2049+
"type": "array"
2050+
}
2051+
},
2052+
"required": [
2053+
"version_downloads"
2054+
],
2055+
"type": "object"
2056+
}
2057+
}
2058+
},
20142059
"description": "Successful Response"
20152060
}
20162061
},

src/views.rs

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -201,10 +201,19 @@ impl EncodableDependency {
201201
}
202202
}
203203

204-
#[derive(Serialize, Deserialize, Debug)]
204+
#[derive(Serialize, Deserialize, Debug, utoipa::ToSchema)]
205+
#[schema(as = VersionDownload)]
205206
pub struct EncodableVersionDownload {
207+
/// The ID of the version this download count is for.
208+
#[schema(example = 42)]
206209
pub version: i32,
210+
211+
/// The number of downloads for this version on the given date.
212+
#[schema(example = 123)]
207213
pub downloads: i32,
214+
215+
/// The date this download count is for.
216+
#[schema(example = "2019-12-13")]
208217
pub date: String,
209218
}
210219

0 commit comments

Comments
 (0)