Merge #5231

5231: Improve openapi r=dureuill a=irevoire

# Pull Request

## Related issue
Fixes https://github.com/meilisearch/open-api/issues/17
Fixes https://github.com/meilisearch/open-api/issues/13
Fixes https://github.com/meilisearch/open-api/issues/14
Fixes https://github.com/meilisearch/open-api/issues/16


Co-authored-by: Tamo <tamo@meilisearch.com>

crates/meilisearch/src/routes/api_key.rs

@@ -54,7 +54,7 @@ pub fn configure(cfg: &mut web::ServiceConfig) {
 /// Create an API Key.
 #[utoipa::path(
     post,
-    path = "/",
+    path = "",
     tag = "Keys",
     security(("Bearer" = ["keys.create", "keys.*", "*"])),
     request_body = CreateApiKey,
@@ -133,7 +133,7 @@ impl ListApiKeys {
 /// List all API Keys
 #[utoipa::path(
     get,
-    path = "/",
+    path = "",
     tag = "Keys",
     security(("Bearer" = ["keys.get", "keys.*", "*"])),
     params(ListApiKeys),

crates/meilisearch/src/routes/batches.rs

@@ -121,7 +121,7 @@ pub struct AllBatches {
 /// Batch results are paginated and can be filtered with query parameters.
 #[utoipa::path(
     get,
-    path = "/",
+    path = "",
     tag = "Batches",
     security(("Bearer" = ["tasks.get", "tasks.*", "*"])),
     params(TasksFilterQuery),

crates/meilisearch/src/routes/dump.rs

@@ -45,7 +45,7 @@ crate::empty_analytics!(DumpAnalytics, "Dump Created");
 /// If the dump directory does not exist yet, it will be created.
 #[utoipa::path(
     post,
-    path = "/",
+    path = "",
     tag = "Dumps",
     security(("Bearer" = ["dumps.create", "dumps.*", "*"])),
     responses(

crates/meilisearch/src/routes/features.rs

@@ -40,18 +40,18 @@ pub fn configure(cfg: &mut web::ServiceConfig) {
 ///
 /// Get a list of all experimental features that can be activated via the /experimental-features route and whether or not they are currently activated.
 #[utoipa::path(
-    post,
+    get,
-    path = "/",
+    path = "",
     tag = "Experimental features",
     security(("Bearer" = ["experimental_features.get", "experimental_features.*", "*"])),
     responses(
-        (status = OK, description = "Experimental features are returned", body = RuntimeTogglableFeatures, content_type = "application/json", example = json!(
+        (status = OK, description = "Experimental features are returned", body = RuntimeTogglableFeatures, content_type = "application/json", example = json!(RuntimeTogglableFeatures {
-            {
+            vector_store: Some(true),
-                "metrics": false,
+            metrics: Some(true),
-                "logsRoute": true,
+            logs_route: Some(false),
-                "vectorSearch": false,
+            edit_documents_by_function: Some(false),
-            }
+            contains_filter: Some(false),
-        )),
+        })),
         (status = 401, description = "The authorization header is missing", body = ResponseError, content_type = "application/json", example = json!(
             {
                 "message": "The Authorization header is missing. It must use the bearer authorization method.",
@@ -75,8 +75,9 @@ async fn get_features(
     HttpResponse::Ok().json(features)
 }
 
-#[derive(Debug, Deserr, ToSchema)]
+#[derive(Debug, Deserr, ToSchema, Serialize)]
 #[deserr(error = DeserrJsonError, rename_all = camelCase, deny_unknown_fields)]
+#[serde(rename_all = "camelCase")]
 #[schema(rename_all = "camelCase")]
 pub struct RuntimeTogglableFeatures {
     #[deserr(default)]
@@ -125,17 +126,17 @@ impl Aggregate for PatchExperimentalFeatureAnalytics {
 /// Activate or deactivate experimental features.
 #[utoipa::path(
     patch,
-    path = "/",
+    path = "",
     tag = "Experimental features",
     security(("Bearer" = ["experimental_features.update", "experimental_features.*", "*"])),
     responses(
-        (status = OK, description = "Experimental features are returned", body = RuntimeTogglableFeatures, content_type = "application/json", example = json!(
+        (status = OK, description = "Experimental features are returned", body = RuntimeTogglableFeatures, content_type = "application/json", example = json!(RuntimeTogglableFeatures {
-            {
+            vector_store: Some(true),
-                "metrics": false,
+            metrics: Some(true),
-                "logsRoute": true,
+            logs_route: Some(false),
-                "vectorSearch": false,
+            edit_documents_by_function: Some(false),
-            }
+            contains_filter: Some(false),
-        )),
+         })),
         (status = 401, description = "The authorization header is missing", body = ResponseError, content_type = "application/json", example = json!(
             {
                 "message": "The Authorization header is missing. It must use the bearer authorization method.",

crates/meilisearch/src/routes/indexes/mod.rs

@@ -135,7 +135,7 @@ impl ListIndexes {
 /// List all indexes.
 #[utoipa::path(
     get,
-    path = "/",
+    path = "",
     tag = "Indexes",
     security(("Bearer" = ["indexes.get", "indexes.*", "*"])),
     params(ListIndexes),
@@ -226,7 +226,7 @@ impl Aggregate for IndexCreatedAggregate {
 /// Create an index.
 #[utoipa::path(
     post,
-    path = "/",
+    path = "",
     tag = "Indexes",
     security(("Bearer" = ["indexes.create", "indexes.*", "*"])),
     request_body = IndexCreateRequest,

crates/meilisearch/src/routes/indexes/settings.rs

@@ -86,6 +86,7 @@ macro_rules! make_setting_route {
                 path = concat!("{indexUid}/settings", $route),
                 tag = "Settings",
                 security(("Bearer" = ["settings.update", "settings.*", "*"])),
+                operation_id = concat!("delete", $camelcase_attr),
                 summary = concat!("Reset ", $camelcase_attr),
                 description = concat!("Reset an index's ", $camelcase_attr, " to its default value"),
                 params(("indexUid", example = "movies", description = "Index Unique Identifier", nullable = false)),
@@ -149,6 +150,7 @@ macro_rules! make_setting_route {
                 path = concat!("{indexUid}/settings", $route),
                 tag = "Settings",
                 security(("Bearer" = ["settings.update", "settings.*", "*"])),
+                operation_id = concat!(stringify!($update_verb), $camelcase_attr),
                 summary = concat!("Update ", $camelcase_attr),
                 description = concat!("Update an index's user defined ", $camelcase_attr),
                 params(("indexUid", example = "movies", description = "Index Unique Identifier", nullable = false)),
@@ -236,6 +238,7 @@ macro_rules! make_setting_route {
                 summary = concat!("Get ", $camelcase_attr),
                 description = concat!("Get an user defined ", $camelcase_attr),
                 security(("Bearer" = ["settings.get", "settings.*", "*"])),
+                operation_id = concat!("get", $camelcase_attr),
                 params(("indexUid", example = "movies", description = "Index Unique Identifier", nullable = false)),
                 responses(
                     (status = 200, description = concat!($camelcase_attr, " is returned"), body = $type, content_type = "application/json", example = json!(

crates/meilisearch/src/routes/metrics.rs

@@ -30,7 +30,7 @@ pub fn configure(config: &mut web::ServiceConfig) {
 /// which means it must be enabled.
 #[utoipa::path(
     get,
-    path = "/",
+    path = "",
     tag = "Stats",
     security(("Bearer" = ["metrics.get", "metrics.*", "*"])),
     responses(

crates/meilisearch/src/routes/mod.rs

@@ -81,6 +81,10 @@ pub mod tasks;
         (name = "Stats", description = "Stats gives extended information and metrics about indexes and the Meilisearch database."),
     ),
     modifiers(&OpenApiAuth),
+    servers((
+        url = "/",
+        description = "Local server",
+    )),
     components(schemas(PaginationView<KeyView>, PaginationView<IndexView>, IndexView, DocumentDeletionByFilter, AllBatches, BatchStats, ProgressStepView, ProgressView, BatchView, RuntimeTogglableFeatures, SwapIndexesPayload, DocumentEditionByFunction, MergeFacets, FederationOptions, SearchQueryWithIndex, Federation, FederatedSearch, FederatedSearchResult, SearchResults, SearchResultWithIndex, SimilarQuery, SimilarResult, PaginationView<serde_json::Value>, BrowseQuery, UpdateIndexRequest, IndexUid, IndexCreateRequest, KeyView, Action, CreateApiKey, UpdateStderrLogs, LogMode, GetLogs, IndexStats, Stats, HealthStatus, HealthResponse, VersionResponse, Code, ErrorType, AllTasks, TaskView, Status, DetailsView, ResponseError, Settings<Unchecked>, Settings<Checked>, TypoSettings, MinWordSizeTyposSetting, FacetingSettings, PaginationSettings, SummarizedTaskView, Kind))
 )]
 pub struct MeilisearchApi;

crates/meilisearch/src/routes/multi_search.rs

@@ -48,7 +48,7 @@ pub struct SearchResults {
 /// Bundle multiple search queries in a single API request. Use this endpoint to search through multiple indexes at once.
 #[utoipa::path(
     post,
-    path = "/",
+    path = "",
     tag = "Multi-search",
     security(("Bearer" = ["search", "*"])),
     responses(

crates/meilisearch/src/routes/snapshot.rs

@@ -39,7 +39,7 @@ crate::empty_analytics!(SnapshotAnalytics, "Snapshot Created");
 /// Triggers a snapshot creation process. Once the process is complete, a snapshot is created in the snapshot directory. If the snapshot directory does not exist yet, it will be created.
 #[utoipa::path(
     post,
-    path = "/",
+    path = "",
     tag = "Snapshots",
     security(("Bearer" = ["snapshots.create", "snapshots.*", "*"])),
     responses(

crates/meilisearch/src/routes/swap_indexes.rs

@@ -63,7 +63,7 @@ impl Aggregate for IndexSwappedAnalytics {
 /// Swapping indexA and indexB will also replace every mention of indexA by indexB and vice-versa in the task history. enqueued tasks are left unmodified.
 #[utoipa::path(
     post,
-    path = "/",
+    path = "",
     tag = "Indexes",
     security(("Bearer" = ["search", "*"])),
     request_body = Vec<SwapIndexesPayload>,