Add some descriptions to utoipa schema

notifico-core/src/engine/mod.rs

@@ -19,6 +19,7 @@ pub use plugin::{EnginePlugin, StepOutput};
 
 #[derive(Debug, Default, Clone, Serialize, Deserialize, ToSchema)]
 #[serde(transparent)]
+/// Event context contains all variables, that will be passed to templating engine.
 pub struct EventContext(pub Map<String, Value>);
 
 #[derive(Default, Clone, Debug, Serialize, Deserialize)]

notifico-core/src/recipient.rs

@@ -6,8 +6,10 @@ use uuid::Uuid;
 #[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 pub struct Recipient {
     #[serde(default = "Uuid::nil")]
+    /// This ID will be used for List-Unsubscribe and other features.
+    /// It is recommended to store it in an external system and use the same ID for the same Recipient.
     pub id: Uuid,
-    #[schema(value_type = String)]
+    #[schema(value_type = Vec<String>, examples("telegram:123456789", "mobile_phone:+123456789", "email:Anyone <[email protected]>"))]
     pub contacts: Vec<Contact>,
 }
 

notifico-ingest/src/http.rs

@@ -8,7 +8,7 @@ use notifico_core::pipeline::event::ProcessEventRequest;
 use serde::Deserialize;
 use std::net::SocketAddr;
 use tokio::net::TcpListener;
-use utoipa::OpenApi;
+use utoipa::{IntoParams, OpenApi};
 use utoipa_redoc::Redoc;
 use utoipa_redoc::Servable;
 use utoipa_swagger_ui::SwaggerUi;
@@ -40,7 +40,11 @@ pub(crate) async fn start(serviceapi_bind: SocketAddr, ext: HttpExtensions) {
     tokio::spawn(async { axum::serve(listener, app).await.unwrap() });
 }
 
-#[utoipa::path(post, path = "/v1/send")]
+#[utoipa::path(
+    post,
+    path = "/v1/send",
+    description = "Send an event to the AMQP event bus. Available worker will then run the pipelines for the corresponding event"
+)]
 async fn send(
     Extension(sender): Extension<Sender<ProcessEventRequest>>,
     Json(payload): Json<ProcessEventRequest>,
@@ -50,14 +54,23 @@ async fn send(
     StatusCode::ACCEPTED
 }
 
-#[derive(Deserialize)]
+#[derive(Deserialize, IntoParams)]
+#[into_params(style = Form, parameter_in = Query)]
 struct WebhookParameters {
     #[serde(default = "Uuid::nil")]
     project_id: Uuid,
     event: String,
 }
 
-#[utoipa::path(post, path = "/v1/send_webhook")]
+#[utoipa::path(
+    post,
+    path = "/v1/send_webhook",
+    params(WebhookParameters),
+    description = "This method accepts any JSON as POST body as a context, so you can use it in your template.
+
+Recipients must be set in Pipeline, using `core.set_recipients` step. This method is intended for any external system that accepts webhook integration,
+so you can create notifications for arbitrary webhooks."
+)]
 async fn send_webhook(
     Extension(sender): Extension<Sender<ProcessEventRequest>>,
     parameters: Query<WebhookParameters>,