utoipa: Use CratePath and CrateVersionPath as params descriptions

Author: Turbo87

src/controllers/krate.rs

@@ -4,6 +4,7 @@ use axum::extract::{FromRequestParts, Path};
 use crates_io_database::schema::crates;
 use diesel::{OptionalExtension, QueryDsl};
 use diesel_async::{AsyncPgConnection, RunQueryDsl};
+use utoipa::IntoParams;
 
 pub mod delete;
 pub mod downloads;
@@ -14,7 +15,8 @@ pub mod publish;
 pub mod search;
 pub mod versions;
 
-#[derive(Deserialize, FromRequestParts)]
+#[derive(Deserialize, FromRequestParts, IntoParams)]
+#[into_params(parameter_in = Path)]
 #[from_request(via(Path))]
 pub struct CratePath {
     /// Name of the crate

src/controllers/krate/delete.rs

@@ -30,6 +30,7 @@ const AVAILABLE_AFTER: TimeDelta = TimeDelta::hours(24);
 #[utoipa::path(
     delete,
     path = "/api/v1/crates/{name}",
+    params(CratePath),
     tag = "crates",
     responses((status = 200, description = "Successful Response")),
 )]

src/controllers/krate/downloads.rs

@@ -23,6 +23,7 @@ use std::cmp;
 #[utoipa::path(
     get,
     path = "/api/v1/crates/{name}/downloads",
+    params(CratePath),
     tag = "crates",
     responses((status = 200, description = "Successful Response")),
 )]

src/controllers/krate/follow.rs

@@ -33,6 +33,7 @@ async fn follow_target(
 #[utoipa::path(
     put,
     path = "/api/v1/crates/{name}/follow",
+    params(CratePath),
     tag = "crates",
     responses((status = 200, description = "Successful Response")),
 )]
@@ -53,6 +54,7 @@ pub async fn follow_crate(app: AppState, path: CratePath, req: Parts) -> AppResu
 #[utoipa::path(
     delete,
     path = "/api/v1/crates/{name}/follow",
+    params(CratePath),
     tag = "crates",
     responses((status = 200, description = "Successful Response")),
 )]
@@ -69,6 +71,7 @@ pub async fn unfollow_crate(app: AppState, path: CratePath, req: Parts) -> AppRe
 #[utoipa::path(
     get,
     path = "/api/v1/crates/{name}/following",
+    params(CratePath),
     tag = "crates",
     responses((status = 200, description = "Successful Response")),
 )]

src/controllers/krate/metadata.rs

@@ -46,6 +46,7 @@ pub async fn find_new_crate(app: AppState, req: Parts) -> AppResult<ErasedJson>
 #[utoipa::path(
     get,
     path = "/api/v1/crates/{name}",
+    params(CratePath),
     tag = "crates",
     responses((status = 200, description = "Successful Response")),
 )]
@@ -248,6 +249,7 @@ impl FromStr for ShowIncludeMode {
 #[utoipa::path(
     get,
     path = "/api/v1/crates/{name}/{version}/readme",
+    params(CrateVersionPath),
     tag = "versions",
     responses((status = 200, description = "Successful Response")),
 )]
@@ -264,6 +266,7 @@ pub async fn get_version_readme(app: AppState, path: CrateVersionPath, req: Part
 #[utoipa::path(
     get,
     path = "/api/v1/crates/{name}/reverse_dependencies",
+    params(CratePath),
     tag = "crates",
     responses((status = 200, description = "Successful Response")),
 )]

src/controllers/krate/owners.rs

@@ -21,6 +21,7 @@ use secrecy::{ExposeSecret, SecretString};
 #[utoipa::path(
     get,
     path = "/api/v1/crates/{name}/owners",
+    params(CratePath),
     tag = "owners",
     responses((status = 200, description = "Successful Response")),
 )]
@@ -43,6 +44,7 @@ pub async fn list_owners(state: AppState, path: CratePath) -> AppResult<ErasedJs
 #[utoipa::path(
     get,
     path = "/api/v1/crates/{name}/owner_team",
+    params(CratePath),
     tag = "owners",
     responses((status = 200, description = "Successful Response")),
 )]
@@ -63,6 +65,7 @@ pub async fn get_team_owners(state: AppState, path: CratePath) -> AppResult<Eras
 #[utoipa::path(
     get,
     path = "/api/v1/crates/{name}/owner_user",
+    params(CratePath),
     tag = "owners",
     responses((status = 200, description = "Successful Response")),
 )]
@@ -84,6 +87,7 @@ pub async fn get_user_owners(state: AppState, path: CratePath) -> AppResult<Eras
 #[utoipa::path(
     put,
     path = "/api/v1/crates/{name}/owners",
+    params(CratePath),
     tag = "owners",
     responses((status = 200, description = "Successful Response")),
 )]
@@ -100,6 +104,7 @@ pub async fn add_owners(
 #[utoipa::path(
     delete,
     path = "/api/v1/crates/{name}/owners",
+    params(CratePath),
     tag = "owners",
     responses((status = 200, description = "Successful Response")),
 )]

src/controllers/krate/versions.rs

@@ -24,6 +24,7 @@ use crate::views::EncodableVersion;
 #[utoipa::path(
     get,
     path = "/api/v1/crates/{name}/versions",
+    params(CratePath),
     tag = "versions",
     responses((status = 200, description = "Successful Response")),
 )]

src/controllers/version.rs

@@ -4,16 +4,19 @@ pub mod yank;
 
 use axum::extract::{FromRequestParts, Path};
 use diesel_async::AsyncPgConnection;
+use utoipa::IntoParams;
 
 use crate::models::{Crate, Version};
 use crate::util::errors::{crate_not_found, AppResult};
 
-#[derive(Deserialize, FromRequestParts)]
+#[derive(Deserialize, FromRequestParts, IntoParams)]
+#[into_params(parameter_in = Path)]
 #[from_request(via(Path))]
 pub struct CrateVersionPath {
     /// Name of the crate
     pub name: String,
     /// Version number
+    #[param(example = "1.0.0")]
     pub version: String,
 }
 

src/controllers/version/downloads.rs

@@ -23,6 +23,7 @@ use http::request::Parts;
 #[utoipa::path(
     get,
     path = "/api/v1/crates/{name}/{version}/download",
+    params(CrateVersionPath),
     tag = "versions",
     responses((status = 200, description = "Successful Response")),
 )]
@@ -46,6 +47,7 @@ pub async fn download_version(
 #[utoipa::path(
     get,
     path = "/api/v1/crates/{name}/{version}/downloads",
+    params(CrateVersionPath),
     tag = "versions",
     responses((status = 200, description = "Successful Response")),
 )]

src/controllers/version/metadata.rs

@@ -49,6 +49,7 @@ pub struct VersionUpdateRequest {
 #[utoipa::path(
     get,
     path = "/api/v1/crates/{name}/{version}/dependencies",
+    params(CrateVersionPath),
     tag = "versions",
     responses((status = 200, description = "Successful Response")),
 )]
@@ -83,6 +84,7 @@ pub async fn get_version_dependencies(
 #[utoipa::path(
     get,
     path = "/api/v1/crates/{name}/{version}/authors",
+    params(CrateVersionPath),
     tag = "versions",
     responses((status = 200, description = "Successful Response")),
 )]
@@ -98,6 +100,7 @@ pub async fn get_version_authors() -> ErasedJson {
 #[utoipa::path(
     get,
     path = "/api/v1/crates/{name}/{version}",
+    params(CrateVersionPath),
     tag = "versions",
     responses((status = 200, description = "Successful Response")),
 )]
@@ -121,6 +124,7 @@ pub async fn find_version(state: AppState, path: CrateVersionPath) -> AppResult<
 #[utoipa::path(
     patch,
     path = "/api/v1/crates/{name}/{version}",
+    params(CrateVersionPath),
     tag = "versions",
     responses((status = 200, description = "Successful Response")),
 )]

src/controllers/version/yank.rs

@@ -23,6 +23,7 @@ use http::request::Parts;
 #[utoipa::path(
     delete,
     path = "/api/v1/crates/{name}/{version}/yank",
+    params(CrateVersionPath),
     tag = "versions",
     responses((status = 200, description = "Successful Response")),
 )]
@@ -38,6 +39,7 @@ pub async fn yank_version(
 #[utoipa::path(
     put,
     path = "/api/v1/crates/{name}/{version}/unyank",
+    params(CrateVersionPath),
     tag = "versions",
     responses((status = 200, description = "Successful Response")),
 )]