improve API docs

thanks @david-crespo and @benjaminleonard for advice!

Author: hawkw

nexus/external-api/src/lib.rs

@@ -3532,7 +3532,7 @@ pub trait NexusExternalApi {
         query_params: Query<PaginatedByNameOrId>,
     ) -> Result<HttpResponseOk<ResultsPage<views::WebhookReceiver>>, HttpError>;
 
-    /// Get the configuration for a webhook receiver.
+    /// Fetch webhook receiver
     #[endpoint {
         method = GET,
         path = "/v1/webhooks/receivers/{receiver}",
@@ -3543,7 +3543,7 @@ pub trait NexusExternalApi {
         path_params: Path<params::WebhookReceiverSelector>,
     ) -> Result<HttpResponseOk<views::WebhookReceiver>, HttpError>;
 
-    /// Create a new webhook receiver.
+    /// Create webhook receiver.
     #[endpoint {
         method = POST,
         path = "/v1/webhooks/receivers",
@@ -3554,7 +3554,11 @@ pub trait NexusExternalApi {
         params: TypedBody<params::WebhookCreate>,
     ) -> Result<HttpResponseCreated<views::WebhookReceiver>, HttpError>;
 
-    /// Update the configuration of an existing webhook receiver.
+    /// Update webhook receiver
+    ///
+    /// Note that receiver secrets are NOT added or removed using this endpoint.
+    /// Instead, use the /v1/webhooks/{secrets}/?receiver={receiver} endpoint
+    /// to add and remove secrets.
     #[endpoint {
         method = PUT,
         path = "/v1/webhooks/receivers/{receiver}",
@@ -3566,7 +3570,7 @@ pub trait NexusExternalApi {
         params: TypedBody<params::WebhookReceiverUpdate>,
     ) -> Result<HttpResponseUpdatedNoContent, HttpError>;
 
-    /// Delete a webhook receiver.
+    /// Delete webhook receiver.
     #[endpoint {
         method = DELETE,
         path = "/v1/webhooks/receivers/{receiver}",
@@ -3577,10 +3581,23 @@ pub trait NexusExternalApi {
         path_params: Path<params::WebhookReceiverSelector>,
     ) -> Result<HttpResponseDeleted, HttpError>;
 
-    /// Send a liveness probe request to a webhook receiver.
-    // TODO(eliza): this return type isn't quite right, as the response should
-    // have a typed body, but any status code, as we return a resposne with the
-    // status code from the webhook endpoint...
+    /// Send liveness probe to webhook receiver
+    ///
+    /// This endpoint synchronously sends a liveness probe request to the
+    /// selected webhook receiver. The response message describes the outcome of
+    /// the probe request: either the response from the receiver endpoint, or an
+    /// indication of why the probe failed.
+    ///
+    /// Note that the response status is 200 OK as long as a probe request was
+    /// able to be sent to the receiver endpoint. If the receiver responds with
+    /// another status code, including an error, this will be indicated by the
+    /// response body, NOT the status of the response.
+    ///
+    /// The "resend" query parameter can be used to request re-delivery of
+    /// failed events if the liveness probe succeeds. If it is set to true and
+    /// the webhook receiver responds to the probe request with a 2xx status
+    /// code, any events for which delivery to this receiver has failed will be
+    /// queued for re-delivery.
     #[endpoint {
         method = POST,
         path = "/v1/webhooks/receivers/{receiver}/probe",
@@ -3592,7 +3609,7 @@ pub trait NexusExternalApi {
         query_params: Query<params::WebhookProbe>,
     ) -> Result<HttpResponseOk<views::WebhookProbeResult>, HttpError>;
 
-    /// List the IDs of secrets for a webhook receiver.
+    /// List webhook receiver secret IDs
     #[endpoint {
         method = GET,
         path = "/v1/webhooks/secrets",
@@ -3603,7 +3620,7 @@ pub trait NexusExternalApi {
         query_params: Query<params::WebhookReceiverSelector>,
     ) -> Result<HttpResponseOk<views::WebhookSecrets>, HttpError>;
 
-    /// Add a secret to a webhook receiver.
+    /// Add secret to webhook receiver
     #[endpoint {
         method = POST,
         path = "/v1/webhooks/secrets",
@@ -3615,7 +3632,7 @@ pub trait NexusExternalApi {
         params: TypedBody<params::WebhookSecretCreate>,
     ) -> Result<HttpResponseCreated<views::WebhookSecretId>, HttpError>;
 
-    /// Delete a secret associated with a webhook receiver by ID.
+    /// Remove secret from webhook receiver
     #[endpoint {
         method = DELETE,
         path = "/v1/webhooks/secrets/{secret_id}",
@@ -3626,7 +3643,13 @@ pub trait NexusExternalApi {
         path_params: Path<params::WebhookSecretSelector>,
     ) -> Result<HttpResponseDeleted, HttpError>;
 
-    /// List delivery attempts to a webhook receiver.
+    /// List delivery attempts to a webhook receiver
+    ///
+    /// Optional query parameters to this endpoint may be used to filter
+    /// deliveries by state. If none of the "failed", "pending", or "delivered"
+    /// query parameters are present, all deliveries are returned. If one or
+    /// more of these parameters are provided, only those which are set to
+    /// "true" are included in the response.
     #[endpoint {
         method = GET,
         path = "/v1/webhooks/deliveries",
@@ -3639,7 +3662,7 @@ pub trait NexusExternalApi {
         pagination: Query<PaginatedById>,
     ) -> Result<HttpResponseOk<ResultsPage<views::WebhookDelivery>>, HttpError>;
 
-    /// Request re-delivery of a webhook event.
+    /// Request re-delivery of webhook event
     #[endpoint {
         method = POST,
         path = "/v1/webhooks/deliveries/{event_id}/resend",

nexus/types/src/external_api/params.rs

@@ -2381,6 +2381,9 @@ pub struct DeviceAccessTokenRequest {
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct EventClassFilter {
     /// An optional glob pattern for filtering event class names.
+    ///
+    /// If provided, only event classes which match this glob pattern will be
+    /// included in the response.
     pub filter: Option<String>,
 }
 
@@ -2432,6 +2435,7 @@ pub struct WebhookReceiverUpdate {
 
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct WebhookSecretCreate {
+    /// The value of the shared secret key.
     pub secret: String,
 }
 
@@ -2443,13 +2447,24 @@ pub struct WebhookSecretSelector {
 
 #[derive(Deserialize, JsonSchema)]
 pub struct WebhookEventSelector {
+    /// UUID of the event
     pub event_id: Uuid,
 }
 
 #[derive(Copy, Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct WebhookDeliveryStateFilter {
+    /// If true, include only deliveries which are currently in progress.
+    ///
+    /// A delivery is considered "pending" if  it has not yet been sent at all,
+    /// or if a delivery attempt has failed but the delivery has retries
+    /// remaining.
     pub pending: Option<bool>,
+    /// If true, include only deliveries which have failed permanently.
+    ///
+    /// A delivery fails permanently when the retry limit of three total
+    /// attempts is reached without a successful delivery.
     pub failed: Option<bool>,
+    /// If true, include only deliveries which have succeeded.
     pub delivered: Option<bool>,
 }
 

openapi/nexus.json

@@ -11935,7 +11935,8 @@
         "tags": [
           "system/webhooks"
         ],
-        "summary": "List delivery attempts to a webhook receiver.",
+        "summary": "List delivery attempts to a webhook receiver",
+        "description": "Optional query parameters to this endpoint may be used to filter deliveries by state. If none of the \"failed\", \"pending\", or \"delivered\" query parameters are present, all deliveries are returned. If one or more of these parameters are provided, only those which are set to \"true\" are included in the response.",
         "operationId": "webhook_delivery_list",
         "parameters": [
           {
@@ -11950,6 +11951,7 @@
           {
             "in": "query",
             "name": "delivered",
+            "description": "If true, include only deliveries which have succeeded.",
             "schema": {
               "nullable": true,
               "type": "boolean"
@@ -11958,6 +11960,7 @@
           {
             "in": "query",
             "name": "failed",
+            "description": "If true, include only deliveries which have failed permanently.\n\nA delivery fails permanently when the retry limit of three total attempts is reached without a successful delivery.",
             "schema": {
               "nullable": true,
               "type": "boolean"
@@ -11966,6 +11969,7 @@
           {
             "in": "query",
             "name": "pending",
+            "description": "If true, include only deliveries which are currently in progress.\n\nA delivery is considered \"pending\" if  it has not yet been sent at all, or if a delivery attempt has failed but the delivery has retries remaining.",
             "schema": {
               "nullable": true,
               "type": "boolean"
@@ -12027,12 +12031,13 @@
         "tags": [
           "system/webhooks"
         ],
-        "summary": "Request re-delivery of a webhook event.",
+        "summary": "Request re-delivery of webhook event",
         "operationId": "webhook_delivery_resend",
         "parameters": [
           {
             "in": "path",
             "name": "event_id",
+            "description": "UUID of the event",
             "required": true,
             "schema": {
               "type": "string",
@@ -12100,7 +12105,7 @@
           {
             "in": "query",
             "name": "filter",
-            "description": "An optional glob pattern for filtering event class names.",
+            "description": "An optional glob pattern for filtering event class names.\n\nIf provided, only event classes which match this glob pattern will be included in the response.",
             "schema": {
               "nullable": true,
               "type": "string"
@@ -12192,7 +12197,7 @@
         "tags": [
           "system/webhooks"
         ],
-        "summary": "Create a new webhook receiver.",
+        "summary": "Create webhook receiver.",
         "operationId": "webhook_receiver_create",
         "requestBody": {
           "content": {
@@ -12229,7 +12234,7 @@
         "tags": [
           "system/webhooks"
         ],
-        "summary": "Get the configuration for a webhook receiver.",
+        "summary": "Fetch webhook receiver",
         "operationId": "webhook_receiver_view",
         "parameters": [
           {
@@ -12265,7 +12270,8 @@
         "tags": [
           "system/webhooks"
         ],
-        "summary": "Update the configuration of an existing webhook receiver.",
+        "summary": "Update webhook receiver",
+        "description": "Note that receiver secrets are NOT added or removed using this endpoint. Instead, use the /v1/webhooks/{secrets}/?receiver={receiver} endpoint to add and remove secrets.",
         "operationId": "webhook_receiver_update",
         "parameters": [
           {
@@ -12304,7 +12310,7 @@
         "tags": [
           "system/webhooks"
         ],
-        "summary": "Delete a webhook receiver.",
+        "summary": "Delete webhook receiver.",
         "operationId": "webhook_receiver_delete",
         "parameters": [
           {
@@ -12335,7 +12341,8 @@
         "tags": [
           "system/webhooks"
         ],
-        "summary": "Send a liveness probe request to a webhook receiver.",
+        "summary": "Send liveness probe to webhook receiver",
+        "description": "This endpoint synchronously sends a liveness probe request to the selected webhook receiver. The response message describes the outcome of the probe request: either the response from the receiver endpoint, or an indication of why the probe failed.\n\nNote that the response status is 200 OK as long as a probe request was able to be sent to the receiver endpoint. If the receiver responds with another status code, including an error, this will be indicated by the response body, NOT the status of the response.\n\nThe \"resend\" query parameter can be used to request re-delivery of failed events if the liveness probe succeeds. If it is set to true and the webhook receiver responds to the probe request with a 2xx status code, any events for which delivery to this receiver has failed will be queued for re-delivery.",
         "operationId": "webhook_receiver_probe",
         "parameters": [
           {
@@ -12381,7 +12388,7 @@
         "tags": [
           "system/webhooks"
         ],
-        "summary": "List the IDs of secrets for a webhook receiver.",
+        "summary": "List webhook receiver secret IDs",
         "operationId": "webhook_secrets_list",
         "parameters": [
           {
@@ -12417,7 +12424,7 @@
         "tags": [
           "system/webhooks"
         ],
-        "summary": "Add a secret to a webhook receiver.",
+        "summary": "Add secret to webhook receiver",
         "operationId": "webhook_secrets_add",
         "parameters": [
           {
@@ -12465,7 +12472,7 @@
         "tags": [
           "system/webhooks"
         ],
-        "summary": "Delete a secret associated with a webhook receiver by ID.",
+        "summary": "Remove secret from webhook receiver",
         "operationId": "webhook_secrets_delete",
         "parameters": [
           {
@@ -25657,6 +25664,7 @@
         "type": "object",
         "properties": {
           "secret": {
+            "description": "The value of the shared secret key.",
             "type": "string"
           }
         },