Merge pull request #113 from threefoldtech/development-fix-swagger

Fix and organize OpenAPI schema

Author: rawdaGastan

rust-toolchain.toml

@@ -1,3 +1,3 @@
 [toolchain]
-channel = "1.74.0"
+channel = "1.83.0"
 

src/server/auth.rs

@@ -38,12 +38,13 @@ pub struct SignInResponse {
 
 #[utoipa::path(
     post,
-    path = "/v1/api/signin",
+    path = "/api/v1/signin",
+    tag = "Authentication",
     request_body = SignInBody,
     responses(
-        (status = 200, description = "User signed in successfully", body = SignInResponse),
-        (status = 500, description = "Internal server error"),
-        (status = 401, description = "Unauthorized user"),
+        (status = 201, description = "User signed in successfully", body = SignInResponse),
+        (status = 500, description = "Internal server error", body = ResponseError),
+        (status = 401, description = "Unauthorized user", body = ResponseError),
     )
 )]
 #[debug_handler]

src/server/block_handlers.rs

@@ -13,20 +13,12 @@ use crate::server::{
     config::AppState,
     db::DB,
     models::Block,
-    response::{ResponseError, ResponseResult},
+    response::{ResponseError, ResponseResult, BlockUploadedResponse},
 };
 use serde::{Deserialize, Serialize};
-use utoipa::{OpenApi, ToSchema};
+use utoipa::ToSchema;
 
-#[derive(OpenApi)]
-#[openapi(
-    paths(upload_block_handler, get_block_handler, check_block_handler, verify_blocks_handler, get_blocks_by_hash_handler, list_blocks_handler, get_user_blocks_handler, get_block_downloads_handler),
-    components(schemas(Block, VerifyBlocksRequest, VerifyBlocksResponse, BlocksResponse, ListBlocksParams, ListBlocksResponse, UserBlocksResponse, BlockDownloadsResponse)),
-    tags(
-        (name = "blocks", description = "Block management API")
-    )
-)]
-pub struct BlockApi;
+// Block API endpoints are included in the main FlistApi in handlers.rs
 
 /// Query parameters for uploading a block
 #[derive(Debug, Serialize, Deserialize, ToSchema)]
@@ -43,16 +35,20 @@ pub struct UploadBlockParams {
 #[utoipa::path(
     post,
     path = "/api/v1/block",
-    request_body(content = Vec<u8>, description = "Block data to upload", content_type = "application/octet-stream"),
+    tag = "Block Management",
+    request_body(content = [u8], description = "Block data to upload", content_type = "application/octet-stream"),
     params(
         ("file_hash" = String, Query, description = "File hash associated with the block"),
         ("idx" = u64, Query, description = "Block index within the file")
     ),
     responses(
-        (status = 200, description = "Block already exists", body = String),
-        (status = 201, description = "Block created successfully", body = String),
-        (status = 400, description = "Bad request"),
-        (status = 500, description = "Internal server error"),
+        (status = 200, description = "Block already exists", body = BlockUploadedResponse),
+        (status = 201, description = "Block created successfully", body = BlockUploadedResponse),
+        (status = 400, description = "Bad request", body = ResponseError),
+        (status = 500, description = "Internal server error", body = ResponseError),
+    ),
+    security(
+        ("bearerAuth" = [])
     )
 )]
 #[debug_handler]
@@ -98,10 +94,11 @@ pub async fn upload_block_handler(
 #[utoipa::path(
     get,
     path = "/api/v1/block/{hash}",
+    tag = "Block Management",
     responses(
-        (status = 200, description = "Block found", content_type = "application/octet-stream"),
-        (status = 404, description = "Block not found"),
-        (status = 500, description = "Internal server error"),
+        (status = 200, description = "Block found", body = [u8], content_type = "application/octet-stream"),
+        (status = 404, description = "Block not found", body = ResponseError),
+        (status = 500, description = "Internal server error", body = ResponseError),
     ),
     params(
         ("hash" = String, Path, description = "Block hash")
@@ -136,9 +133,10 @@ pub async fn get_block_handler(
 #[utoipa::path(
     head,
     path = "/api/v1/block/{hash}",
+    tag = "Block Management",
     responses(
         (status = 200, description = "Block found"),
-        (status = 404, description = "Block not found"),
+        (status = 404, description = "Block not found", body = ResponseError),
     ),
     params(
         ("hash" = String, Path, description = "Block hash")
@@ -194,11 +192,12 @@ pub struct VerifyBlocksResponse {
 #[utoipa::path(
     post,
     path = "/api/v1/block/verify",
+    tag = "Block Management",
     request_body(content = VerifyBlocksRequest, description = "List of block hashes to verify", content_type = "application/json"),
     responses(
         (status = 200, description = "Verification completed", body = VerifyBlocksResponse),
-        (status = 400, description = "Bad request"),
-        (status = 500, description = "Internal server error"),
+        (status = 400, description = "Bad request", body = ResponseError),
+        (status = 500, description = "Internal server error", body = ResponseError),
     )
 )]
 #[debug_handler]
@@ -228,11 +227,29 @@ pub async fn verify_blocks_handler(
     ))
 }
 
+/// Block information with hash and index
+#[derive(Debug, Serialize, Deserialize, ToSchema)]
+pub struct BlockInfo {
+    /// Block hash
+    pub hash: String,
+    /// Block index within the file
+    pub index: u64,
+}
+
+/// Block information with hash and size
+#[derive(Debug, Serialize, Deserialize, ToSchema)]
+pub struct UserBlockInfo {
+    /// Block hash
+    pub hash: String,
+    /// Block size in bytes
+    pub size: u64,
+}
+
 /// Response for blocks by hash endpoint
 #[derive(Debug, Serialize, Deserialize, ToSchema)]
 pub struct BlocksResponse {
     /// List of blocks with their indices
-    pub blocks: Vec<(String, u64)>,
+    pub blocks: Vec<BlockInfo>,
 }
 
 /// Retrieve blocks by hash (file hash or block hash).
@@ -241,10 +258,11 @@ pub struct BlocksResponse {
 #[utoipa::path(
     get,
     path = "/api/v1/blocks/{hash}",
+    tag = "Block Management",
     responses(
         (status = 200, description = "Blocks found", body = BlocksResponse),
-        (status = 404, description = "Hash not found"),
-        (status = 500, description = "Internal server error"),
+        (status = 404, description = "Hash not found", body = ResponseError),
+        (status = 500, description = "Internal server error", body = ResponseError),
     ),
     params(
         ("hash" = String, Path, description = "File hash or block hash")
@@ -259,7 +277,10 @@ pub async fn get_blocks_by_hash_handler(
     match state.db.get_file_blocks_ordered(&hash).await {
         Ok(blocks) if !blocks.is_empty() => {
             // This is a file hash, return all blocks with their indices
-            Ok((StatusCode::OK, Json(BlocksResponse { blocks })))
+            let block_infos = blocks.into_iter()
+                .map(|(hash, index)| BlockInfo { hash, index })
+                .collect();
+            Ok((StatusCode::OK, Json(BlocksResponse { blocks: block_infos })))
         }
         Ok(_) | Err(_) => {
             // Not a file hash or error occurred, try as block hash
@@ -269,7 +290,7 @@ pub async fn get_blocks_by_hash_handler(
                     Ok((
                         StatusCode::OK,
                         Json(BlocksResponse {
-                            blocks: vec![(hash.clone(), 0)],
+                            blocks: vec![BlockInfo { hash: hash.clone(), index: 0 }],
                         }),
                     ))
                 }
@@ -317,6 +338,7 @@ pub struct ListBlocksResponse {
 #[utoipa::path(
     get,
     path = "/api/v1/blocks",
+    tag = "Block Management",
     params(
         ("page" = Option<u32>, Query, description = "Page number (1-indexed)"),
         ("per_page" = Option<u32>, Query, description = "Number of items per page")
@@ -356,7 +378,7 @@ pub async fn list_blocks_handler(
 #[derive(Debug, Serialize, Deserialize, ToSchema)]
 pub struct UserBlocksResponse {
     /// List of blocks with their sizes
-    pub blocks: Vec<(String, u64)>,
+    pub blocks: Vec<UserBlockInfo>,
     /// Total number of blocks
     pub total: u64,
     /// Total number of all blocks
@@ -367,6 +389,7 @@ pub struct UserBlocksResponse {
 #[utoipa::path(
     get,
     path = "/api/v1/user/blocks",
+    tag = "Block Management",
     params(
         ("page" = Option<u32>, Query, description = "Page number (1-indexed)"),
         ("per_page" = Option<u32>, Query, description = "Number of items per page")
@@ -375,6 +398,9 @@ pub struct UserBlocksResponse {
         (status = 200, description = "Blocks found", body = UserBlocksResponse),
         (status = 401, description = "Unauthorized"),
         (status = 500, description = "Internal server error"),
+    ),
+    security(
+        ("bearerAuth" = [])
     )
 )]
 #[debug_handler]
@@ -403,7 +429,9 @@ pub async fn get_user_blocks_handler(
         Ok(blocks) => {
             let total = blocks.len() as u64;
             let response = UserBlocksResponse {
-                blocks,
+                blocks: blocks.into_iter()
+                .map(|(hash, size)| UserBlockInfo { hash, size })
+                .collect(),
                 total,
                 all_blocks,
             };
@@ -431,6 +459,7 @@ pub struct BlockDownloadsResponse {
 #[utoipa::path(
     get,
     path = "/api/v1/block/{hash}/downloads",
+    tag = "Block Management",
     responses(
         (status = 200, description = "Download count retrieved successfully", body = BlockDownloadsResponse),
         (status = 404, description = "Block not found"),

src/server/file_handlers.rs

@@ -10,19 +10,11 @@ use crate::server::{
     response::{ResponseError, ResponseResult},
 };
 use serde::{Deserialize, Serialize};
-use utoipa::{OpenApi, ToSchema};
+use utoipa::ToSchema;
 
 const BLOCK_SIZE: usize = 1024 * 1024; // 1MB
 
-#[derive(OpenApi)]
-#[openapi(
-    paths(upload_file_handler, get_file_handler),
-    components(schemas(File, FileUploadResponse, FileDownloadRequest)),
-    tags(
-        (name = "files", description = "File management API")
-    )
-)]
-pub struct FileApi;
+// File API endpoints are included in the main FlistApi in handlers.rs
 
 /// Response for file upload
 #[derive(Debug, Serialize, Deserialize, ToSchema)]
@@ -38,11 +30,15 @@ pub struct FileUploadResponse {
 #[utoipa::path(
     post,
     path = "/api/v1/file",
-    request_body(content = Vec<u8>, description = "File data to upload", content_type = "application/octet-stream"),
+    tag = "File Management",
+    request_body(content = [u8], description = "File data to upload", content_type = "application/octet-stream"),
     responses(
         (status = 201, description = "File uploaded successfully", body = FileUploadResponse),
-        (status = 400, description = "Bad request"),
-        (status = 500, description = "Internal server error"),
+        (status = 400, description = "Bad request", body = ResponseError),
+        (status = 500, description = "Internal server error", body = ResponseError),
+    ),
+    security(
+        ("bearerAuth" = [])
     )
 )]
 #[debug_handler]
@@ -120,13 +116,14 @@ pub struct FileDownloadRequest {
 /// Retrieve a file by its hash from path, with optional custom filename in request body.
 /// The file will be reconstructed from its blocks.
 #[utoipa::path(
-    post,
+    get,
     path = "/api/v1/file/{hash}",
+    tag = "File Management",
     request_body(content = FileDownloadRequest, description = "Optional custom filename for download", content_type = "application/json"),
     responses(
-        (status = 200, description = "File found", content_type = "application/octet-stream"),
-        (status = 404, description = "File not found"),
-        (status = 500, description = "Internal server error"),
+        (status = 200, description = "File found", body = [u8], content_type = "application/octet-stream"),
+        (status = 404, description = "File not found", body = ResponseError),
+        (status = 500, description = "Internal server error", body = ResponseError),
     ),
     params(
         ("hash" = String, Path, description = "File hash")