admin api: add comments for InspectObject

src/api/admin/api.rs

@@ -918,25 +918,40 @@ pub struct InspectObjectRequest {
 #[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "camelCase")]
 pub struct InspectObjectResponse {
+	/// ID of the bucket containing the inspected object
 	pub bucket_id: String,
+	/// Key of the inspected object
 	pub key: String,
+	/// List of versions currently stored for this object
 	pub versions: Vec<InspectObjectVersion>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, ToSchema, Default)]
 #[serde(rename_all = "camelCase")]
 pub struct InspectObjectVersion {
+	/// Version ID
 	pub uuid: String,
+	/// Creation timestamp of this object version
 	pub timestamp: chrono::DateTime<chrono::Utc>,
+	/// Whether this object version was created with SSE-C encryption
 	pub encrypted: bool,
+	/// Whether this object version is still uploading
 	pub uploading: bool,
+	/// Whether this is an aborted upload
 	pub aborted: bool,
+	/// Whether this version is a delete marker (a tombstone indicating that a previous version of
+	/// the object has been deleted)
 	pub delete_marker: bool,
+	/// Whether the object's data is stored inline (for small objects)
 	pub inline: bool,
+	/// Size of the object, in bytes
 	pub size: Option<u64>,
+	/// Etag of this object version
 	pub etag: Option<String>,
+	/// Metadata (HTTP headers) associated with this object version
 	#[serde(default, skip_serializing_if = "Vec::is_empty")]
 	pub headers: Vec<(String, String)>,
+	/// List of data blocks for this object version
 	#[serde(default, skip_serializing_if = "Vec::is_empty")]
 	pub blocks: Vec<InspectObjectBlock>,
 }
@@ -944,9 +959,13 @@ pub struct InspectObjectVersion {
 #[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "camelCase")]
 pub struct InspectObjectBlock {
+	/// Part number of the part containing this block, for multipart uploads
 	pub part_number: u64,
+	/// Offset of this block within the part
 	pub offset: u64,
+	/// Hash (blake2 sum) of the block's data
 	pub hash: String,
+	/// Length of the blocks's data
 	pub size: u64,
 }
 

src/api/admin/bucket.rs

@@ -365,7 +365,7 @@ impl RequestHandler for InspectObjectRequest {
 			.object_table
 			.get(&bucket_id, &self.key)
 			.await?
-			.ok_or_else(|| Error::bad_request("object not found"))?;
+			.ok_or_else(|| Error::NoSuchKey)?;
 
 		let mut versions = vec![];
 		for obj_ver in object.versions().iter() {

src/api/admin/error.rs

@@ -37,6 +37,10 @@ pub enum Error {
 	#[error(display = "Worker not found: {}", _0)]
 	NoSuchWorker(u64),
 
+	/// The object requested don't exists
+	#[error(display = "Key not found")]
+	NoSuchKey,
+
 	/// In Import key, the key already exists
 	#[error(
 		display = "Key {} already exists in data store. Even if it is deleted, we can't let you create a new key with the same ID. Sorry.",
@@ -69,6 +73,7 @@ impl Error {
 			Error::NoSuchWorker(_) => "NoSuchWorker",
 			Error::NoSuchBlock(_) => "NoSuchBlock",
 			Error::KeyAlreadyExists(_) => "KeyAlreadyExists",
+			Error::NoSuchKey => "NoSuchKey",
 		}
 	}
 }
@@ -81,7 +86,8 @@ impl ApiError for Error {
 			Error::NoSuchAdminToken(_)
 			| Error::NoSuchAccessKey(_)
 			| Error::NoSuchWorker(_)
-			| Error::NoSuchBlock(_) => StatusCode::NOT_FOUND,
+			| Error::NoSuchBlock(_)
+			| Error::NoSuchKey => StatusCode::NOT_FOUND,
 			Error::KeyAlreadyExists(_) => StatusCode::CONFLICT,
 		}
 	}

src/api/admin/openapi.rs

@@ -514,10 +514,18 @@ fn CleanupIncompleteUploads() -> () {}
     tag = "Bucket",
     description = "
 Returns detailed information about an object in a bucket, including its internal state in Garage.
+
+This API call can be used to list the data blocks referenced by an object,
+as well as to view metadata associated to the object.
+
+This call may return a list of more than one version for the object, for instance in the
+case where there is a currently stored version of the object, and a newer version whose
+upload is in progress and not yet finished.
     ",
     params(InspectObjectRequest),
 	responses(
             (status = 200, description = "Returns exhaustive information about the object", body = InspectObjectResponse),
+            (status = 404, description = "Object not found"),
             (status = 500, description = "Internal server error")
         ),
 )]