Merge #711

711: Add support for sorting on the documents API r=curquiza a=kumarUjjawal

# Pull Request

## Related issue
Fixes #699 

## What does this PR do?

As per the requirements of the [Meilisearch 1.16](https://www.meilisearch.com/blog/meilisearch-1-16?utm_campaign=oss&utm_medium=integrations) the goal was to update the SDK to allow the sorting on the documents API.

## PR checklist
Please check if your PR fulfills the following requirements:
- [x] Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
- [x] Have you read the contributing guidelines?
- [x] Have you made sure that the title is accurate and descriptive of the changes?

Thank you so much for contributing to Meilisearch!


<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

* **New Features**
  * Added sorting options to document retrieval, allowing results to be ordered by specified attributes when sorting is configured. Supports multi-attribute sorting. Default behavior remains unchanged if no sort is provided.
* **Tests**
  * Added test coverage to verify correct ordering of documents when sorting is applied.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: Kumar Ujjawal <[email protected]>

Author: meili-bors[bot]

src/documents.rs

@@ -190,6 +190,12 @@ pub struct DocumentsQuery<'a, Http: HttpClient> {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub fields: Option<Vec<&'a str>>,
 
+    /// Attributes used to sort the returned documents.
+    ///
+    /// Available since v1.16 of Meilisearch.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub sort: Option<Vec<&'a str>>,
+
     /// Filters to apply.
     ///
     /// Available since v1.2 of Meilisearch
@@ -206,6 +212,7 @@ impl<'a, Http: HttpClient> DocumentsQuery<'a, Http> {
             offset: None,
             limit: None,
             fields: None,
+            sort: None,
             filter: None,
         }
     }
@@ -277,6 +284,31 @@ impl<'a, Http: HttpClient> DocumentsQuery<'a, Http> {
         self
     }
 
+    /// Specify the sort order of the returned documents.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use meilisearch_sdk::{client::*, indexes::*, documents::*};
+    /// #
+    /// # let MEILISEARCH_URL = option_env!("MEILISEARCH_URL").unwrap_or("http://localhost:7700");
+    /// # let MEILISEARCH_API_KEY = option_env!("MEILISEARCH_API_KEY").unwrap_or("masterKey");
+    /// #
+    /// # let client = Client::new(MEILISEARCH_URL, Some(MEILISEARCH_API_KEY)).unwrap();
+    /// let index = client.index("documents_with_sort");
+    ///
+    /// let mut documents_query = DocumentsQuery::new(&index);
+    ///
+    /// documents_query.with_sort(["release_date:desc"]);
+    /// ```
+    pub fn with_sort(
+        &mut self,
+        sort: impl IntoIterator<Item = &'a str>,
+    ) -> &mut DocumentsQuery<'a, Http> {
+        self.sort = Some(sort.into_iter().collect());
+        self
+    }
+
     pub fn with_filter<'b>(&'b mut self, filter: &'a str) -> &'b mut DocumentsQuery<'a, Http> {
         self.filter = Some(filter);
         self
@@ -538,6 +570,33 @@ mod tests {
         Ok(())
     }
 
+    #[meilisearch_test]
+    async fn test_get_documents_with_sort(client: Client, index: Index) -> Result<(), Error> {
+        setup_test_index(&client, &index).await?;
+
+        index
+            .set_sortable_attributes(["id"])
+            .await?
+            .wait_for_completion(&client, None, None)
+            .await?;
+
+        let documents = DocumentsQuery::new(&index)
+            .with_sort(["id:desc"])
+            .execute::<MyObject>()
+            .await?;
+
+        assert_eq!(
+            documents.results.first().and_then(|document| document.id),
+            Some(3)
+        );
+        assert_eq!(
+            documents.results.last().and_then(|document| document.id),
+            Some(0)
+        );
+
+        Ok(())
+    }
+
     #[meilisearch_test]
     async fn test_get_documents_with_error_hint() -> Result<(), Error> {
         let meilisearch_url = option_env!("MEILISEARCH_URL").unwrap_or("http://localhost:7700");