Implements the get and delete tasks route

2025-07-04 12:27:13 +02:00 · 2024-08-08 19:14:19 +02:00 · 2024-08-08 19:14:19 +02:00 · 742d0ee531
commit 742d0ee531
parent f00a285a6d
25 changed files with 1787 additions and 85 deletions
--- a/crates/meilisearch-types/Cargo.toml
+++ b/crates/meilisearch-types/Cargo.toml
@ -40,6 +40,7 @@ time = { version = "0.3.36", features = [
    "macros",
 ] }
 tokio = "1.38"
+utoipa = { version = "5.0.0-rc.0", features = ["macros"] }
 uuid = { version = "1.10.0", features = ["serde", "v4"] }

 [dev-dependencies]
--- a/crates/meilisearch-types/src/deserr/query_params.rs
+++ b/crates/meilisearch-types/src/deserr/query_params.rs
@ -16,6 +16,7 @@ use std::ops::Deref;
 use std::str::FromStr;

 use deserr::{DeserializeError, Deserr, MergeWithError, ValueKind};
+use utoipa::{PartialSchema, ToSchema};

 use super::{DeserrParseBoolError, DeserrParseIntError};
 use crate::index_uid::IndexUid;
@ -29,6 +30,18 @@ use crate::tasks::{Kind, Status};
 #[derive(Default, Debug, Clone, Copy)]
 pub struct Param<T>(pub T);

+impl<T: ToSchema> ToSchema for Param<T> {
+    fn name() -> std::borrow::Cow<'static, str> {
+        T::name()
+    }
+}
+
+impl<T: PartialSchema> PartialSchema for Param<T> {
+    fn schema() -> utoipa::openapi::RefOr<utoipa::openapi::schema::Schema> {
+        T::schema()
+    }
+}
+
 impl<T> Deref for Param<T> {
    type Target = T;

--- a/crates/meilisearch-types/src/error.rs
+++ b/crates/meilisearch-types/src/error.rs
@ -7,17 +7,25 @@ use aweb::rt::task::JoinError;
 use convert_case::Casing;
 use milli::heed::{Error as HeedError, MdbError};
 use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;

-#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
+#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq, ToSchema)]
 #[serde(rename_all = "camelCase")]
+#[schema(rename_all = "camelCase")]
 pub struct ResponseError {
    #[serde(skip)]
    pub code: StatusCode,
+    /// The error message.
    pub message: String,
+    /// The error code.
+    #[schema(value_type = Code)]
    #[serde(rename = "code")]
    error_code: String,
+    /// The error type.
+    #[schema(value_type = ErrorType)]
    #[serde(rename = "type")]
    error_type: String,
+    /// A link to the documentation about this specific error.
    #[serde(rename = "link")]
    error_link: String,
 }
@ -97,7 +105,9 @@ pub trait ErrorCode {
 }

 #[allow(clippy::enum_variant_names)]
-enum ErrorType {
+#[derive(ToSchema)]
+#[schema(rename_all = "snake_case")]
+pub enum ErrorType {
    Internal,
    InvalidRequest,
    Auth,
@ -129,7 +139,8 @@ impl fmt::Display for ErrorType {
 /// `MyErrorCode::default().error_code()`.
 macro_rules! make_error_codes {
    ($($code_ident:ident, $err_type:ident, $status:ident);*) => {
-        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+        #[derive(Debug, Clone, Copy, PartialEq, Eq, ToSchema)]
+        #[schema(rename_all = "snake_case")]
        pub enum Code {
            $($code_ident),*
        }
--- a/crates/meilisearch-types/src/facet_values_sort.rs
+++ b/crates/meilisearch-types/src/facet_values_sort.rs
@ -1,8 +1,9 @@
 use deserr::Deserr;
 use milli::OrderBy;
 use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;

-#[derive(Debug, Default, Copy, Clone, PartialEq, Eq, Serialize, Deserialize, Deserr)]
+#[derive(Debug, Default, Copy, Clone, PartialEq, Eq, Serialize, Deserialize, Deserr, ToSchema)]
 #[serde(rename_all = "camelCase")]
 #[deserr(rename_all = camelCase)]
 pub enum FacetValuesSort {
--- a/crates/meilisearch-types/src/index_uid.rs
+++ b/crates/meilisearch-types/src/index_uid.rs
@ -4,13 +4,15 @@ use std::fmt;
 use std::str::FromStr;

 use deserr::Deserr;
+use utoipa::ToSchema;

 use crate::error::{Code, ErrorCode};

 /// An index uid is composed of only ascii alphanumeric characters, - and _, between 1 and 400
 /// bytes long
-#[derive(Debug, Clone, PartialEq, Eq, Deserr, PartialOrd, Ord)]
+#[derive(Debug, Clone, PartialEq, Eq, Deserr, PartialOrd, Ord, ToSchema)]
 #[deserr(try_from(String) = IndexUid::try_from -> IndexUidFormatError)]
+#[schema(value_type = String, example = "movies")]
 pub struct IndexUid(String);

 impl IndexUid {
--- a/crates/meilisearch-types/src/keys.rs
+++ b/crates/meilisearch-types/src/keys.rs
@ -9,6 +9,7 @@ use serde::{Deserialize, Serialize};
 use time::format_description::well_known::Rfc3339;
 use time::macros::{format_description, time};
 use time::{Date, OffsetDateTime, PrimitiveDateTime};
+use utoipa::ToSchema;
 use uuid::Uuid;

 use crate::deserr::{immutable_field_error, DeserrError, DeserrJsonError};
@ -32,19 +33,31 @@ impl<C: Default + ErrorCode> MergeWithError<IndexUidPatternFormatError> for Dese
    }
 }

-#[derive(Debug, Deserr)]
+#[derive(Debug, Deserr, ToSchema)]
 #[deserr(error = DeserrJsonError, rename_all = camelCase, deny_unknown_fields)]
+#[schema(rename_all = "camelCase")]
 pub struct CreateApiKey {
+    /// A description for the key. `null` if empty.
+    #[schema(example = json!(null))]
    #[deserr(default, error = DeserrJsonError<InvalidApiKeyDescription>)]
    pub description: Option<String>,
+    /// A human-readable name for the key. `null` if empty.
+    #[schema(example = "Indexing Products API key")]
    #[deserr(default, error = DeserrJsonError<InvalidApiKeyName>)]
    pub name: Option<String>,
+    /// A uuid v4 to identify the API Key. If not specified, it's generated by Meilisearch.
+    #[schema(value_type = Uuid, example = json!(null))]
    #[deserr(default = Uuid::new_v4(), error = DeserrJsonError<InvalidApiKeyUid>, try_from(&String) = Uuid::from_str -> uuid::Error)]
    pub uid: KeyId,
+    /// A list of actions permitted for the key. `["*"]` for all actions. The `*` character can be used as a wildcard when located at the last position. e.g. `documents.*` to authorize access on all documents endpoints.
+    #[schema(example = json!(["documents.add"]))]
    #[deserr(error = DeserrJsonError<InvalidApiKeyActions>, missing_field_error = DeserrJsonError::missing_api_key_actions)]
    pub actions: Vec<Action>,
+    /// A list of accesible indexes permitted for the key. `["*"]` for all indexes. The `*` character can be used as a wildcard when located at the last position. e.g. `products_*` to allow access to all indexes whose names start with `products_`.
    #[deserr(error = DeserrJsonError<InvalidApiKeyIndexes>, missing_field_error = DeserrJsonError::missing_api_key_indexes)]
+    #[schema(value_type = Vec<String>, example = json!(["products"]))]
    pub indexes: Vec<IndexUidPattern>,
+    /// Represent the expiration date and time as RFC 3339 format. `null` equals to no expiration time.
    #[deserr(error = DeserrJsonError<InvalidApiKeyExpiresAt>, try_from(Option<String>) = parse_expiration_date -> ParseOffsetDateTimeError, missing_field_error = DeserrJsonError::missing_api_key_expires_at)]
    pub expires_at: Option<OffsetDateTime>,
 }
@ -86,12 +99,15 @@ fn deny_immutable_fields_api_key(
    }
 }

-#[derive(Debug, Deserr)]
+#[derive(Debug, Deserr, ToSchema)]
 #[deserr(error = DeserrJsonError, rename_all = camelCase, deny_unknown_fields = deny_immutable_fields_api_key)]
+#[schema(rename_all = "camelCase")]
 pub struct PatchApiKey {
    #[deserr(default, error = DeserrJsonError<InvalidApiKeyDescription>)]
+    #[schema(value_type = Option<String>, example = "This key is used to update documents in the products index")]
    pub description: Setting<String>,
    #[deserr(default, error = DeserrJsonError<InvalidApiKeyName>)]
+    #[schema(value_type = Option<String>, example = "Indexing Products API key")]
    pub name: Setting<String>,
 }

@ -179,7 +195,9 @@ fn parse_expiration_date(
    }
 }

-#[derive(Copy, Clone, Serialize, Deserialize, Debug, Eq, PartialEq, Hash, Sequence, Deserr)]
+#[derive(
+    Copy, Clone, Serialize, Deserialize, Debug, Eq, PartialEq, Hash, Sequence, Deserr, ToSchema,
+)]
 #[repr(u8)]
 pub enum Action {
    #[serde(rename = "*")]
--- a/crates/meilisearch-types/src/locales.rs
+++ b/crates/meilisearch-types/src/locales.rs
@ -1,8 +1,9 @@
 use deserr::Deserr;
 use milli::LocalizedAttributesRule;
 use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;

-#[derive(Debug, Clone, PartialEq, Eq, Deserr, Serialize, Deserialize)]
+#[derive(Debug, Clone, PartialEq, Eq, Deserr, Serialize, Deserialize, ToSchema)]
 #[deserr(rename_all = camelCase)]
 #[serde(rename_all = "camelCase")]
 pub struct LocalizedAttributesRuleView {
@ -33,7 +34,7 @@ impl From<LocalizedAttributesRuleView> for LocalizedAttributesRule {
 /// this enum implements `Deserr` in order to be used in the API.
 macro_rules! make_locale {
    ($(($iso_639_1:ident, $iso_639_1_str:expr) => ($iso_639_3:ident, $iso_639_3_str:expr),)+) => {
-        #[derive(Debug, Copy, Clone, PartialEq, Eq, Deserr, Serialize, Deserialize, Ord, PartialOrd)]
+        #[derive(Debug, Copy, Clone, PartialEq, Eq, Deserr, Serialize, Deserialize, Ord, PartialOrd, ToSchema)]
        #[deserr(rename_all = camelCase)]
        #[serde(rename_all = "camelCase")]
        pub enum Locale {
--- a/crates/meilisearch-types/src/settings.rs
+++ b/crates/meilisearch-types/src/settings.rs
@ -13,6 +13,7 @@ use milli::proximity::ProximityPrecision;
 use milli::update::Setting;
 use milli::{Criterion, CriterionError, Index, DEFAULT_VALUES_PER_FACET};
 use serde::{Deserialize, Serialize, Serializer};
+use utoipa::ToSchema;

 use crate::deserr::DeserrJsonError;
 use crate::error::deserr_codes::*;
@ -39,10 +40,10 @@ where
    .serialize(s)
 }

-#[derive(Clone, Default, Debug, Serialize, PartialEq, Eq)]
+#[derive(Clone, Default, Debug, Serialize, PartialEq, Eq, ToSchema)]
 pub struct Checked;

-#[derive(Clone, Default, Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[derive(Clone, Default, Debug, Serialize, Deserialize, PartialEq, Eq, ToSchema)]
 pub struct Unchecked;

 impl<E> Deserr<E> for Unchecked
@ -69,54 +70,63 @@ fn validate_min_word_size_for_typo_setting<E: DeserializeError>(
    Ok(s)
 }

-#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq, Deserr)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq, Deserr, ToSchema)]
 #[serde(deny_unknown_fields, rename_all = "camelCase")]
 #[deserr(deny_unknown_fields, rename_all = camelCase, validate = validate_min_word_size_for_typo_setting -> DeserrJsonError<InvalidSettingsTypoTolerance>)]
 pub struct MinWordSizeTyposSetting {
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default)]
+    #[schema(value_type = Option<u8>, example = json!(5))]
    pub one_typo: Setting<u8>,
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default)]
+    #[schema(value_type = Option<u8>, example = json!(9))]
    pub two_typos: Setting<u8>,
 }

-#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq, Deserr)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq, Deserr, ToSchema)]
 #[serde(deny_unknown_fields, rename_all = "camelCase")]
 #[deserr(deny_unknown_fields, rename_all = camelCase, where_predicate = __Deserr_E: deserr::MergeWithError<DeserrJsonError<InvalidSettingsTypoTolerance>>)]
 pub struct TypoSettings {
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default)]
+    #[schema(value_type = Option<bool>, example = json!(true))]
    pub enabled: Setting<bool>,
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsTypoTolerance>)]
+    #[schema(value_type = Option<MinWordSizeTyposSetting>, example = json!({ "oneTypo": 5, "twoTypo": 9 }))]
    pub min_word_size_for_typos: Setting<MinWordSizeTyposSetting>,
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default)]
+    #[schema(value_type = Option<BTreeSet<String>>, example = json!(["iPhone", "phone"]))]
    pub disable_on_words: Setting<BTreeSet<String>>,
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default)]
+    #[schema(value_type = Option<BTreeSet<String>>, example = json!(["uuid", "url"]))]
    pub disable_on_attributes: Setting<BTreeSet<String>>,
 }

-#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq, Deserr)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq, Deserr, ToSchema)]
 #[serde(deny_unknown_fields, rename_all = "camelCase")]
 #[deserr(rename_all = camelCase, deny_unknown_fields)]
 pub struct FacetingSettings {
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default)]
+    #[schema(value_type = Option<usize>, example = json!(10))]
    pub max_values_per_facet: Setting<usize>,
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default)]
+    #[schema(value_type = Option<BTreeMap<String, FacetValuesSort>>, example = json!({ "genre": FacetValuesSort::Count }))]
    pub sort_facet_values_by: Setting<BTreeMap<String, FacetValuesSort>>,
 }

-#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq, Deserr)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq, Deserr, ToSchema)]
 #[serde(deny_unknown_fields, rename_all = "camelCase")]
 #[deserr(rename_all = camelCase, deny_unknown_fields)]
 pub struct PaginationSettings {
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default)]
+    #[schema(value_type = Option<usize>, example = json!(250))]
    pub max_total_hits: Setting<usize>,
 }

@ -137,70 +147,105 @@ impl MergeWithError<milli::CriterionError> for DeserrJsonError<InvalidSettingsRa
 /// Holds all the settings for an index. `T` can either be `Checked` if they represents settings
 /// whose validity is guaranteed, or `Unchecked` if they need to be validated. In the later case, a
 /// call to `check` will return a `Settings<Checked>` from a `Settings<Unchecked>`.
-#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq, Deserr)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq, Deserr, ToSchema)]
 #[serde(
    deny_unknown_fields,
    rename_all = "camelCase",
    bound(serialize = "T: Serialize", deserialize = "T: Deserialize<'static>")
 )]
 #[deserr(error = DeserrJsonError, rename_all = camelCase, deny_unknown_fields)]
+#[schema(rename_all = "camelCase")]
 pub struct Settings<T> {
+    /// Fields displayed in the returned documents.
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsDisplayedAttributes>)]
+    #[schema(value_type = Option<Vec<String>>, example = json!(["id", "title", "description", "url"]))]
    pub displayed_attributes: WildcardSetting,
-
+    /// Fields in which to search for matching query words sorted by order of importance.
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsSearchableAttributes>)]
+    #[schema(value_type = Option<Vec<String>>, example = json!(["title", "description"]))]
    pub searchable_attributes: WildcardSetting,
-
+    /// Attributes to use for faceting and filtering. See [Filtering and Faceted Search](https://www.meilisearch.com/docs/learn/filtering_and_sorting/search_with_facet_filters).
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsFilterableAttributes>)]
+    #[schema(value_type = Option<Vec<String>>, example = json!(["release_date", "genre"]))]
    pub filterable_attributes: Setting<BTreeSet<String>>,
+    /// Attributes to use when sorting search results.
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsSortableAttributes>)]
+    #[schema(value_type = Option<Vec<String>>, example = json!(["release_date"]))]
    pub sortable_attributes: Setting<BTreeSet<String>>,
+    /// List of ranking rules sorted by order of importance. The order is customizable.
+    /// [A list of ordered built-in ranking rules](https://www.meilisearch.com/docs/learn/relevancy/relevancy).
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsRankingRules>)]
+    #[schema(value_type = Option<Vec<String>>, example = json!([RankingRuleView::Words, RankingRuleView::Typo, RankingRuleView::Proximity, RankingRuleView::Attribute, RankingRuleView::Exactness]))]
    pub ranking_rules: Setting<Vec<RankingRuleView>>,
+    /// List of words ignored when present in search queries.
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsStopWords>)]
+    #[schema(value_type = Option<Vec<String>>, example = json!(["the", "a", "them", "their"]))]
    pub stop_words: Setting<BTreeSet<String>>,
+    /// List of characters not delimiting where one term begins and ends.
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsNonSeparatorTokens>)]
+    #[schema(value_type = Option<Vec<String>>, example = json!([" ", "\n"]))]
    pub non_separator_tokens: Setting<BTreeSet<String>>,
+    /// List of characters delimiting where one term begins and ends.
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsSeparatorTokens>)]
+    #[schema(value_type = Option<Vec<String>>, example = json!(["S"]))]
    pub separator_tokens: Setting<BTreeSet<String>>,
+    /// List of strings Meilisearch should parse as a single term.
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsDictionary>)]
+    #[schema(value_type = Option<Vec<String>>, example = json!(["iPhone pro"]))]
    pub dictionary: Setting<BTreeSet<String>>,
+    /// List of associated words treated similarly. A word associated to an array of word as synonyms.
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsSynonyms>)]
+    #[schema(value_type = Option<BTreeMap<String, Vec<String>>>, example = json!({ "he": ["she", "they", "them"], "phone": ["iPhone", "android"]}))]
    pub synonyms: Setting<BTreeMap<String, Vec<String>>>,
+    /// Search returns documents with distinct (different) values of the given field.
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsDistinctAttribute>)]
+    #[schema(value_type = Option<String>, example = json!("sku"))]
    pub distinct_attribute: Setting<String>,
+    /// Precision level when calculating the proximity ranking rule.
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsProximityPrecision>)]
+    #[schema(value_type = Option<String>, example = json!(ProximityPrecisionView::ByAttribute))]
    pub proximity_precision: Setting<ProximityPrecisionView>,
+    /// Customize typo tolerance feature.
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsTypoTolerance>)]
+    #[schema(value_type = Option<TypoSettings>, example = json!({ "enabled": true, "disableOnAttributes": ["title"]}))]
    pub typo_tolerance: Setting<TypoSettings>,
+    /// Faceting settings.
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsFaceting>)]
+    #[schema(value_type = Option<FacetingSettings>, example = json!({ "maxValuesPerFacet": 10, "sortFacetValuesBy": { "genre": FacetValuesSort::Count }}))]
    pub faceting: Setting<FacetingSettings>,
+    /// Pagination settings.
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsPagination>)]
+    #[schema(value_type = Option<PaginationSettings>, example = json!({ "maxValuesPerFacet": 10, "sortFacetValuesBy": { "genre": FacetValuesSort::Count }}))]
    pub pagination: Setting<PaginationSettings>,

+    /// Embedder required for performing meaning-based search queries.
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsEmbedders>)]
+    #[schema(value_type = String)] // TODO: TAMO
    pub embedders: Setting<BTreeMap<String, Setting<milli::vector::settings::EmbeddingSettings>>>,
+    /// Maximum duration of a search query.
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsSearchCutoffMs>)]
+    #[schema(value_type = Option<u64>, example = json!(50))]
    pub search_cutoff_ms: Setting<u64>,
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsLocalizedAttributes>)]
+    #[schema(value_type = Option<Vec<LocalizedAttributesRuleView>>, example = json!(50))]
    pub localized_attributes: Setting<Vec<LocalizedAttributesRuleView>>,
    #[serde(default, skip_serializing_if = "Setting::is_not_set")]
    #[deserr(default, error = DeserrJsonError<InvalidSettingsFacetSearch>)]
--- a/crates/meilisearch-types/src/task_view.rs
+++ b/crates/meilisearch-types/src/task_view.rs
@ -7,26 +7,42 @@ use crate::error::ResponseError;
 use crate::settings::{Settings, Unchecked};
 use crate::tasks::{serialize_duration, Details, IndexSwap, Kind, Status, Task, TaskId};

-#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, ToSchema)]
 #[serde(rename_all = "camelCase")]
+#[schema(rename_all = "camelCase")]
 pub struct TaskView {
+    /// The unique sequential identifier of the task.
+    #[schema(value_type = u32, example = 4312)]
    pub uid: TaskId,
+    /// The unique identifier of the index where this task is operated.
+    #[schema(example = json!("movies"))]
    pub batch_uid: Option<BatchId>,
    #[serde(default)]
    pub index_uid: Option<String>,
    pub status: Status,
+    /// The type of the task.
    #[serde(rename = "type")]
    pub kind: Kind,
+    /// The uid of the task that performed the taskCancelation if the task has been canceled.
+    #[schema(value_type = Option<u32>, example = json!(4326))]
    pub canceled_by: Option<TaskId>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub details: Option<DetailsView>,
    pub error: Option<ResponseError>,
+    /// Total elasped time the engine was in processing state expressed as a `ISO-8601` duration format.
+    #[schema(value_type = Option<String>, example = json!(null))]
    #[serde(serialize_with = "serialize_duration", default)]
    pub duration: Option<Duration>,
+    /// An `RFC 3339` format for date/time/duration.
+    #[schema(value_type = String, example = json!("2024-08-08_14:12:09.393Z"))]
    #[serde(with = "time::serde::rfc3339")]
    pub enqueued_at: OffsetDateTime,
+    /// An `RFC 3339` format for date/time/duration.
+    #[schema(value_type = String, example = json!("2024-08-08_14:12:09.393Z"))]
    #[serde(with = "time::serde::rfc3339::option", default)]
    pub started_at: Option<OffsetDateTime>,
+    /// An `RFC 3339` format for date/time/duration.
+    #[schema(value_type = String, example = json!("2024-08-08_14:12:09.393Z"))]
    #[serde(with = "time::serde::rfc3339::option", default)]
    pub finished_at: Option<OffsetDateTime>,
 }
@ -53,32 +69,44 @@ impl TaskView {
 #[derive(Default, Debug, PartialEq, Eq, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct DetailsView {
+    /// Number of documents received for documentAdditionOrUpdate task.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub received_documents: Option<u64>,
+    /// Number of documents finally indexed for documentAdditionOrUpdate task or a documentAdditionOrUpdate batch of tasks.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub indexed_documents: Option<Option<u64>>,
+    /// Number of documents edited for editDocumentByFunction task.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub edited_documents: Option<Option<u64>>,
+    /// Value for the primaryKey field encountered if any for indexCreation or indexUpdate task.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub primary_key: Option<Option<String>>,
+    /// Number of provided document ids for the documentDeletion task.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub provided_ids: Option<usize>,
+    /// Number of documents finally deleted for documentDeletion and indexDeletion tasks.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub deleted_documents: Option<Option<u64>>,
+    /// Number of tasks that match the request for taskCancelation or taskDeletion tasks.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub matched_tasks: Option<u64>,
+    /// Number of tasks canceled for taskCancelation.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub canceled_tasks: Option<Option<u64>>,
+    /// Number of tasks deleted for taskDeletion.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub deleted_tasks: Option<Option<u64>>,
+    /// Original filter query for taskCancelation or taskDeletion tasks.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub original_filter: Option<Option<String>>,
+    /// Identifier generated for the dump for dumpCreation task.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub dump_uid: Option<Option<String>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub context: Option<Option<Object>>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub function: Option<String>,
+    /// [Learn more about the settings in this guide](https://www.meilisearch.com/docs/reference/api/settings).
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(flatten)]
    pub settings: Option<Box<Settings<Unchecked>>>,
--- a/crates/meilisearch-types/src/tasks.rs
+++ b/crates/meilisearch-types/src/tasks.rs
@ -9,6 +9,7 @@ use milli::Object;
 use roaring::RoaringBitmap;
 use serde::{Deserialize, Serialize, Serializer};
 use time::{Duration, OffsetDateTime};
+use utoipa::ToSchema;
 use uuid::Uuid;

 use crate::batches::BatchId;
@ -151,7 +152,7 @@ pub enum KindWithContent {
    SnapshotCreation,
 }

-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "camelCase")]
 pub struct IndexSwap {
    pub indexes: (String, String),
@ -363,9 +364,22 @@ impl From<&KindWithContent> for Option<Details> {
    }
 }

+/// The status of a task.
 #[derive(
-    Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Sequence, PartialOrd, Ord,
+    Debug,
+    Clone,
+    Copy,
+    PartialEq,
+    Eq,
+    Hash,
+    Serialize,
+    Deserialize,
+    Sequence,
+    PartialOrd,
+    Ord,
+    ToSchema,
 )]
+#[schema(example = json!(Status::Processing))]
 #[serde(rename_all = "camelCase")]
 pub enum Status {
    Enqueued,
@ -424,10 +438,23 @@ impl fmt::Display for ParseTaskStatusError {
 }
 impl std::error::Error for ParseTaskStatusError {}

+/// The type of the task.
 #[derive(
-    Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Sequence, PartialOrd, Ord,
+    Debug,
+    Clone,
+    Copy,
+    PartialEq,
+    Eq,
+    Hash,
+    Serialize,
+    Deserialize,
+    Sequence,
+    PartialOrd,
+    Ord,
+    ToSchema,
 )]
 #[serde(rename_all = "camelCase")]
+#[schema(rename_all = "camelCase", example = json!(enum_iterator::all::<Kind>().collect::<Vec<_>>()))]
 pub enum Kind {
    DocumentAdditionOrUpdate,
    DocumentEdition,
@ -444,6 +471,10 @@ pub enum Kind {
 }

 impl Kind {
+    pub fn all_variants() -> Vec<Self> {
+        enum_iterator::all::<Kind>().collect()
+    }
+
    pub fn related_to_one_index(&self) -> bool {
        match self {
            Kind::DocumentAdditionOrUpdate