feat: 为 openapi 添加 example

Author: z0z0r4

src/models/curseforge/requests.rs

@@ -48,6 +48,7 @@ impl Display for SearchQuery {
 #[derive(Serialize, Deserialize, Debug, ToSchema)]
 pub struct ModsBody {
     #[serde(rename = "modIds")]
+    #[schema(default = "[238222]")]
     pub mod_ids: Vec<i32>,
     #[serde(rename = "filterPcOnly")]
     pub filter_pc_only: Option<bool>,
@@ -67,19 +68,23 @@ pub struct ModFilesQuery {
 #[derive(Serialize, Deserialize, Debug, ToSchema)]
 pub struct FileIdsBody {
     #[serde(rename = "fileIds")]
+    #[schema(default = "[6614392]")]
     pub file_ids: Vec<i32>,
 }
 
 #[derive(Serialize, Deserialize, Debug, ToSchema)]
 pub struct FingerprintsBody {
+    #[schema(default = "[510490952]")]
     pub fingerprints: Vec<i64>,
 }
 
 #[derive(Serialize, Deserialize, Debug, ToSchema)]
 pub struct CategoriesQuery {
     #[serde(rename = "gameId")]
+    #[schema(default = 432)]
     pub game_id: i32,
     #[serde(rename = "classId")]
+    #[schema(default = 6)]
     pub class_id: Option<i32>,
     #[serde(rename = "classOnly")]
     pub class_only: Option<bool>,

src/models/modrinth/requests.rs

@@ -23,21 +23,29 @@ impl Display for SearchQuery {
 
 #[derive(Debug, Serialize, Deserialize, Clone, ToSchema)]
 pub struct HashesQuery {
+    #[schema(default = "[\"d67e66ea4bb2409997b636dae4203d33764cdcc8\"]")]
     pub hashes: Vec<String>,
+    #[schema(default = "sha1")]
     pub algorithm: String,
 }
 
 #[derive(Debug, Serialize, Deserialize, Clone, ToSchema)]
 pub struct UpdateItems {
+    #[schema(default = "[\"fabric\"]")]
     pub loaders: Vec<String>,
+    #[schema(default = "[\"1.16.5\"]")]
     pub game_versions: Vec<String>,
 }
 
 #[derive(Debug, Serialize, Deserialize, Clone, ToSchema)]
 pub struct MultiUpdateItems {
+    #[schema(default = "[\"d67e66ea4bb2409997b636dae4203d33764cdcc8\"]")]
     pub hashes: Vec<String>,
+    #[schema(default = "sha1")]
     pub algorithm: String,
+    #[schema(default = "[\"fabric\"]")]
     pub loaders: Vec<String>,
+    #[schema(default = "[\"1.16.5\"]")]
     pub game_versions: Vec<String>,
 }
 
@@ -48,6 +56,7 @@ pub struct ProjectIds {
 
 #[derive(Debug, Serialize, Deserialize, Clone, ToSchema)]
 pub struct AlgorithmItems {
+    #[schema(default = "[\"sha512\"]")]
     pub algorithm: String,
 }
 

src/routes/curseforge.rs

@@ -128,7 +128,7 @@ async fn search_mods_cached(
     get,
     path = "/curseforge/v1/mods/{mod_id}",
     params(
-        ("mod_id" = i32, Path, description = "ID of the mod to retrieve")
+        ("mod_id" = i32, Path, description = "ID of the mod to retrieve", example = 238222)
     ),
     responses(
         (status = 200, description = "Mod found", body = ModResponse),
@@ -187,11 +187,11 @@ async fn get_mods(
     get,
     path = "/curseforge/v1/mods/{mod_id}/files",
     params(
-        ("mod_id" = i32, Path, description = "ID of the mod to retrieve files for"),
+        ("mod_id" = i32, Path, description = "ID of the mod to retrieve files for", example = 238222),
         ("gameVersion" = Option<String>, Query, description = "Game version filter (optional)"),
         ("modLoaderType" = Option<String>, Query, description = "Mod loader type filter (optional)"),
-        ("index" = Option<i32>, Query, description = "Index for pagination (optional)"),
-        ("pageSize" = Option<i32>, Query, description = "Page size for pagination (optional)")
+        ("index" = Option<i32>, Query, description = "Index for pagination (optional)", example = 0),
+        ("pageSize" = Option<i32>, Query, description = "Page size for pagination (optional)", example = 50)
     ),
     responses(
         (status = 200, description = "Files found", body = Vec<FileResponse>),

src/routes/modrinth.rs

@@ -49,7 +49,7 @@ pub async fn root() -> impl Responder {
     path = "/modrinth/v2/search",
     params(
         ("query" = Option<String>, Query, description = "Search query", example = "sodium"),
-        ("facets" = Option<String>, Query, description = "Facets to filter results", example = "[['categories:forge'],['versions:1.17.1'],['project_type:mod'],['license:mit']]"),
+        ("facets" = Option<String>, Query, description = "Facets to filter results", example = "[[\"categories:forge\"],[\"versions:1.17.1\"],[\"project_type:mod\"],[\"license:mit\"]]"),
         ("offset" = Option<i32>, Query, description = "Offset for pagination", example = "0"),
         ("limit" = Option<i32>, Query, description = "Limit for pagination", example = "10"),
         ("index" = Option<String>, Query, description = "Index to sort", example = "relevance")
@@ -123,7 +123,7 @@ pub async fn search_cached(
     get,
     path = "/modrinth/v2/project/{project_id}",
     params(
-        ("project_id" = String, Path, description = "ID of the game to filter project"),
+        ("project_id" = String, Path, description = "ID of the game to filter project", example = "sodium"),
     ),
     responses(
         (status = 200, description = "Project found", body = Project)
@@ -147,7 +147,7 @@ pub async fn get_project(
     get,
     path = "/modrinth/v2/projects",
     params(
-        ("ids" = String, Query, description = "The IDs and/or slugs of the projects", example = "['AABBCCDD', 'EEFFGGHH]'")
+        ("ids" = String, Query, description = "The IDs and/or slugs of the projects", example = "[\"sodium\", \"fabric-api\"]")
     ),
     responses(
         (status = 200, description = "Projects Found", body = Vec<Project>),
@@ -177,7 +177,7 @@ pub async fn get_projects(
     get,
     path = "/modrinth/v2/project/{project_id}/version",
     params(
-        ("project_id" = String, Path, description = "ID or slug of the project")
+        ("project_id" = String, Path, description = "ID or slug of the project", example = "sodium")
     ),
     responses(
         (status = 200, description = "Project versions found", body = Vec<Version>)
@@ -218,7 +218,7 @@ pub async fn get_project_versions(
     get,
     path = "/modrinth/v2/version/{version_id}",
     params(
-        ("version_id" = String, Path, description = "ID of the version")
+        ("version_id" = String, Path, description = "ID of the version", example = "ygf8cVZg")
     ),
     responses(
         (status = 200, description = "Version found", body = Version)
@@ -242,7 +242,7 @@ pub async fn get_version(
     get,
     path = "/modrinth/v2/versions",
     params(
-        ("ids" = String, Query, description = "The IDs of the versions", example = "['AABBCCDD', 'EEFFGGHH]'")
+        ("ids" = String, Query, description = "The IDs of the versions", example = "[\"RncWhTxD\", \"ygf8cVZg\"]")
     ),
     responses(
         (status = 200, description = "Versions found", body = Vec<Version>)
@@ -272,8 +272,8 @@ pub async fn get_versions(
     get,
     path = "/modrinth/v2/version_file/{hash}",
     params(
-        ("hash" = String, Path, description = "Hash of the file, sha1 or sha512"),
-        ("algorithm" = String, Query, description = "Hash algorithm used, sha1 or sha512")
+        ("hash" = String, Path, description = "Hash of the file, sha1 or sha512", example = "d67e66ea4bb2409997b636dae4203d33764cdcc8"),
+        ("algorithm" = String, Query, description = "Hash algorithm used, sha1 or sha512", example = "sha1")
     ),
     responses(
         (status = 200, description = "File found", body = Version)
@@ -327,8 +327,8 @@ pub async fn get_version_files(
     path = "/modrinth/v2/version_file/{hash}/update",
     request_body = UpdateItems,
     params(
-        ("hash" = String, Path, description = "Hash of the file, sha1 or sha512"),
-        ("algorithm" = String, Query, description = "Hash algorithm used, sha1 or sha512")
+        ("hash" = String, Path, description = "Hash of the file, sha1 or sha512", example = "d67e66ea4bb2409997b636dae4203d33764cdcc8"),
+        ("algorithm" = String, Query, description = "Hash algorithm used, sha1 or sha512", example = "sha1")
     ),
     responses(
         (status = 200, description = "File updated", body = Version)
@@ -361,6 +361,7 @@ pub async fn update_version_file(
 #[utoipa::path(
     post,
     path = "/modrinth/v2/version_files/update",
+    request_body = MultiUpdateItems,
     responses(
         (status = 200, description = "Versions Found", body = Vec<Version>)
     ),