From 8d6c5bf89b354f1e89096f690b3ea8844086c4fe Mon Sep 17 00:00:00 2001 From: Tamo Date: Mon, 7 Oct 2024 12:17:04 +0200 Subject: [PATCH] write the doc of all the parameters --- meilisearch/src/routes/open_api_utils.rs | 24 ++++ meilisearch/src/routes/tasks.rs | 148 +++++++++++++++++------ 2 files changed, 132 insertions(+), 40 deletions(-) create mode 100644 meilisearch/src/routes/open_api_utils.rs diff --git a/meilisearch/src/routes/open_api_utils.rs b/meilisearch/src/routes/open_api_utils.rs new file mode 100644 index 000000000..71690f52d --- /dev/null +++ b/meilisearch/src/routes/open_api_utils.rs @@ -0,0 +1,24 @@ +use serde::Serialize; +use utoipa::openapi::security::{HttpAuthScheme, HttpBuilder, SecurityScheme}; + +#[derive(Debug, Serialize)] +pub(super) struct OpenApiAuth; + +impl utoipa::Modify for OpenApiAuth { + fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) { + if let Some(schema) = openapi.components.as_mut() { + schema.add_security_scheme( + "Bearer", + SecurityScheme::Http( + HttpBuilder::new() + .scheme(HttpAuthScheme::Bearer) + .bearer_format("Uuidv4, string or JWT") + .description(Some( +"An API key is a token that you provide when making API calls. Include the token in a header parameter called `Authorization`. +Example: `Authorization: Bearer 8fece4405662dd830e4cb265e7e047aab2e79672a760a12712d2a263c9003509`")) + .build(), + ), + ); + } + } +} diff --git a/meilisearch/src/routes/tasks.rs b/meilisearch/src/routes/tasks.rs index bd8852949..134798810 100644 --- a/meilisearch/src/routes/tasks.rs +++ b/meilisearch/src/routes/tasks.rs @@ -69,39 +69,48 @@ pub struct TasksFilterQuery { #[deserr(default, error = DeserrQueryParamError)] #[param(required = false, value_type = Option, example = 12421)] pub from: Option>, - /// Permits to filter tasks by their uid. By default, when the uids query parameter is not set, all task uids are returned. It's possible to specify several uids by separating them with the `,` character. #[deserr(default, error = DeserrQueryParamError)] #[param(required = false, value_type = Option>, example = json!([231, 423, 598, "*"]))] pub uids: OptionStarOrList, + /// Permits to filter tasks using the uid of the task that canceled them. It's possible to specify several task uids by separating them with the `,` character. #[deserr(default, error = DeserrQueryParamError)] #[param(required = false, value_type = Option>, example = json!([374, "*"]))] pub canceled_by: OptionStarOrList, + /// Permits to filter tasks by their related type. By default, when `types` query parameter is not set, all task types are returned. It's possible to specify several types by separating them with the `,` character. #[deserr(default, error = DeserrQueryParamError)] #[param(required = false, value_type = Option>, example = json!([Kind::DocumentAdditionOrUpdate, "*"]))] pub types: OptionStarOrList, + /// Permits to filter tasks by their status. By default, when `statuses` query parameter is not set, all task statuses are returned. It's possible to specify several statuses by separating them with the `,` character. #[deserr(default, error = DeserrQueryParamError)] #[param(required = false, value_type = Option>, example = json!([Status::Succeeded, Status::Failed, Status::Canceled, Status::Enqueued, Status::Processing, "*"]))] pub statuses: OptionStarOrList, + /// Permits to filter tasks by their related index. By default, when `indexUids` query parameter is not set, the tasks of all the indexes are returned. It is possible to specify several indexes by separating them with the `,` character. #[deserr(default, error = DeserrQueryParamError)] #[param(required = false, value_type = Option>, example = json!(["movies", "theater", "*"]))] pub index_uids: OptionStarOrList, + /// Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued after the given date. Supports RFC 3339 date format. #[deserr(default, error = DeserrQueryParamError, try_from(OptionStarOr) = deserialize_date_after -> InvalidTaskDateError)] #[param(required = false, value_type = Option, example = json!(["2024-08-08T16:37:09.971Z", "*"]))] pub after_enqueued_at: OptionStarOr, + /// Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued before the given date. Supports RFC 3339 date format. #[deserr(default, error = DeserrQueryParamError, try_from(OptionStarOr) = deserialize_date_before -> InvalidTaskDateError)] #[param(required = false, value_type = Option, example = json!(["2024-08-08T16:37:09.971Z", "*"]))] pub before_enqueued_at: OptionStarOr, + /// Permits to filter tasks based on their startedAt time. Matches tasks started after the given date. Supports RFC 3339 date format. #[deserr(default, error = DeserrQueryParamError, try_from(OptionStarOr) = deserialize_date_after -> InvalidTaskDateError)] #[param(required = false, value_type = Option, example = json!(["2024-08-08T16:37:09.971Z", "*"]))] pub after_started_at: OptionStarOr, + /// Permits to filter tasks based on their startedAt time. Matches tasks started before the given date. Supports RFC 3339 date format. #[deserr(default, error = DeserrQueryParamError, try_from(OptionStarOr) = deserialize_date_before -> InvalidTaskDateError)] #[param(required = false, value_type = Option, example = json!(["2024-08-08T16:37:09.971Z", "*"]))] pub before_started_at: OptionStarOr, + /// Permits to filter tasks based on their finishedAt time. Matches tasks finished after the given date. Supports RFC 3339 date format. #[deserr(default, error = DeserrQueryParamError, try_from(OptionStarOr) = deserialize_date_after -> InvalidTaskDateError)] #[param(required = false, value_type = Option, example = json!(["2024-08-08T16:37:09.971Z", "*"]))] pub after_finished_at: OptionStarOr, + /// Permits to filter tasks based on their finishedAt time. Matches tasks finished before the given date. Supports RFC 3339 date format. #[deserr(default, error = DeserrQueryParamError, try_from(OptionStarOr) = deserialize_date_before -> InvalidTaskDateError)] #[param(required = false, value_type = Option, example = json!(["2024-08-08T16:37:09.971Z", "*"]))] pub before_finished_at: OptionStarOr, @@ -152,37 +161,48 @@ impl TaskDeletionOrCancelationQuery { #[deserr(error = DeserrQueryParamError, rename_all = camelCase, deny_unknown_fields)] #[into_params(rename_all = "camelCase", parameter_in = Query)] pub struct TaskDeletionOrCancelationQuery { + /// Permits to filter tasks by their uid. By default, when the `uids` query parameter is not set, all task uids are returned. It's possible to specify several uids by separating them with the `,` character. #[deserr(default, error = DeserrQueryParamError)] #[param(required = false, value_type = Option>, example = json!([231, 423, 598, "*"]))] pub uids: OptionStarOrList, + /// Permits to filter tasks using the uid of the task that canceled them. It's possible to specify several task uids by separating them with the `,` character. #[deserr(default, error = DeserrQueryParamError)] #[param(required = false, value_type = Option>, example = json!([374, "*"]))] pub canceled_by: OptionStarOrList, + /// Permits to filter tasks by their related type. By default, when `types` query parameter is not set, all task types are returned. It's possible to specify several types by separating them with the `,` character. #[deserr(default, error = DeserrQueryParamError)] #[param(required = false, value_type = Option>, example = json!([Kind::DocumentDeletion, "*"]))] pub types: OptionStarOrList, + /// Permits to filter tasks by their status. By default, when `statuses` query parameter is not set, all task statuses are returned. It's possible to specify several statuses by separating them with the `,` character. #[deserr(default, error = DeserrQueryParamError)] #[param(required = false, value_type = Option>, example = json!([Status::Succeeded, Status::Failed, Status::Canceled, "*"]))] pub statuses: OptionStarOrList, + /// Permits to filter tasks by their related index. By default, when `indexUids` query parameter is not set, the tasks of all the indexes are returned. It is possible to specify several indexes by separating them with the `,` character. #[deserr(default, error = DeserrQueryParamError)] #[param(required = false, value_type = Option>, example = json!(["movies", "theater", "*"]))] pub index_uids: OptionStarOrList, + /// Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued after the given date. Supports RFC 3339 date format. #[deserr(default, error = DeserrQueryParamError, try_from(OptionStarOr) = deserialize_date_after -> InvalidTaskDateError)] #[param(required = false, value_type = Option, example = json!(["2024-08-08T16:37:09.971Z", "*"]))] pub after_enqueued_at: OptionStarOr, + /// Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued before the given date. Supports RFC 3339 date format. #[deserr(default, error = DeserrQueryParamError, try_from(OptionStarOr) = deserialize_date_before -> InvalidTaskDateError)] #[param(required = false, value_type = Option, example = json!(["2024-08-08T16:37:09.971Z", "*"]))] pub before_enqueued_at: OptionStarOr, + /// Permits to filter tasks based on their startedAt time. Matches tasks started after the given date. Supports RFC 3339 date format. #[deserr(default, error = DeserrQueryParamError, try_from(OptionStarOr) = deserialize_date_after -> InvalidTaskDateError)] #[param(required = false, value_type = Option, example = json!(["2024-08-08T16:37:09.971Z", "*"]))] pub after_started_at: OptionStarOr, + /// Permits to filter tasks based on their startedAt time. Matches tasks started before the given date. Supports RFC 3339 date format. #[deserr(default, error = DeserrQueryParamError, try_from(OptionStarOr) = deserialize_date_before -> InvalidTaskDateError)] #[param(required = false, value_type = Option, example = json!(["2024-08-08T16:37:09.971Z", "*"]))] pub before_started_at: OptionStarOr, + /// Permits to filter tasks based on their finishedAt time. Matches tasks finished after the given date. Supports RFC 3339 date format. #[deserr(default, error = DeserrQueryParamError, try_from(OptionStarOr) = deserialize_date_after -> InvalidTaskDateError)] #[param(required = false, value_type = Option, example = json!(["2024-08-08T16:37:09.971Z", "*"]))] pub after_finished_at: OptionStarOr, + /// Permits to filter tasks based on their finishedAt time. Matches tasks finished before the given date. Supports RFC 3339 date format. #[deserr(default, error = DeserrQueryParamError, try_from(OptionStarOr) = deserialize_date_before -> InvalidTaskDateError)] #[param(required = false, value_type = Option, example = json!(["2024-08-08T16:37:09.971Z", "*"]))] pub before_finished_at: OptionStarOr, @@ -215,15 +235,34 @@ impl TaskDeletionOrCancelationQuery { post, path = "/cancel", tag = "Tasks", + security(("Bearer" = ["tasks.cancel", "tasks.*", "*"])), params(TaskDeletionOrCancelationQuery), responses( - (status = 200, description = "Task successfully enqueued", body = SummarizedTaskView, content_type = "application/json", example = json!({ - "taskUid": 147, - "indexUid": null, - "status": "enqueued", - "type": "taskDeletion", - "enqueuedAt": "2024-08-08T17:05:55.791772Z" - })) + (status = 200, description = "Task successfully enqueued", body = SummarizedTaskView, content_type = "application/json", example = json!( + { + "taskUid": 147, + "indexUid": null, + "status": "enqueued", + "type": "taskCancelation", + "enqueuedAt": "2024-08-08T17:05:55.791772Z" + } + )), + (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.", + "code": "missing_authorization_header", + "type": "auth", + "link": "https://docs.meilisearch.com/errors#missing_authorization_header" + } + )), + (status = 404, description = "The task uid does not exists", body = ResponseError, content_type = "application/json", example = json!( + { + "message": "Task :taskUid not found.", + "code": "task_not_found", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors/#task_not_found" + } + )) ) )] async fn cancel_tasks( @@ -284,15 +323,34 @@ async fn cancel_tasks( delete, path = "", tag = "Tasks", + security(("Bearer" = ["tasks.delete", "tasks.*", "*"])), params(TaskDeletionOrCancelationQuery), responses( - (status = 200, description = "Task successfully enqueued", body = SummarizedTaskView, content_type = "application/json", example = json!({ - "taskUid": 147, - "indexUid": null, - "status": "enqueued", - "type": "taskDeletion", - "enqueuedAt": "2024-08-08T17:05:55.791772Z" - })) + (status = 200, description = "Task successfully enqueued", body = SummarizedTaskView, content_type = "application/json", example = json!( + { + "taskUid": 147, + "indexUid": null, + "status": "enqueued", + "type": "taskDeletion", + "enqueuedAt": "2024-08-08T17:05:55.791772Z" + } + )), + (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.", + "code": "missing_authorization_header", + "type": "auth", + "link": "https://docs.meilisearch.com/errors#missing_authorization_header" + } + )), + (status = 404, description = "The task uid does not exists", body = ResponseError, content_type = "application/json", example = json!( + { + "message": "Task :taskUid not found.", + "code": "task_not_found", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors/#task_not_found" + } + )) ) )] async fn delete_tasks( @@ -368,33 +426,43 @@ pub struct AllTasks { security(("Bearer" = ["tasks.get", "tasks.*", "*"])), params(TasksFilterQuery), responses( - (status = 200, description = "Get all tasks", body = AllTasks, content_type = "application/json", example = json!({ - "results": [ + (status = 200, description = "Get all tasks", body = AllTasks, content_type = "application/json", example = json!( { - "uid": 144, - "indexUid": "mieli", - "status": "succeeded", - "type": "settingsUpdate", - "canceledBy": null, - "details": { - "settings": { - "filterableAttributes": [ - "play_count" - ] - } - }, - "error": null, - "duration": "PT0.009330S", - "enqueuedAt": "2024-08-08T09:01:13.348471Z", - "startedAt": "2024-08-08T09:01:13.349442Z", - "finishedAt": "2024-08-08T09:01:13.358772Z" + "results": [ + { + "uid": 144, + "indexUid": "mieli", + "status": "succeeded", + "type": "settingsUpdate", + "canceledBy": null, + "details": { + "settings": { + "filterableAttributes": [ + "play_count" + ] + } + }, + "error": null, + "duration": "PT0.009330S", + "enqueuedAt": "2024-08-08T09:01:13.348471Z", + "startedAt": "2024-08-08T09:01:13.349442Z", + "finishedAt": "2024-08-08T09:01:13.358772Z" + } + ], + "total": 1, + "limit": 1, + "from": 144, + "next": null } - ], - "total": 1, - "limit": 1, - "from": 144, - "next": null - })) + )), + (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.", + "code": "missing_authorization_header", + "type": "auth", + "link": "https://docs.meilisearch.com/errors#missing_authorization_header" + } + )), ) )] async fn get_tasks(