Improve OpenAPI documentation for PUT /api/v1/me/crate_owner_invitations/{crate_id} endpoints

Author: Turbo87

src/controllers/crate_owner_invitation.rs

@@ -14,8 +14,6 @@ use crate::views::{
 };
 use axum::Json;
 use axum::extract::{FromRequestParts, Path, Query};
-use axum_extra::json;
-use axum_extra::response::ErasedJson;
 use chrono::Utc;
 use diesel::pg::Pg;
 use diesel::prelude::*;
@@ -329,6 +327,12 @@ pub struct OwnerInvitation {
     crate_owner_invite: InvitationResponse,
 }
 
+#[derive(Debug, Serialize, utoipa::ToSchema)]
+pub struct HandleResponse {
+    #[schema(inline)]
+    crate_owner_invitation: InvitationResponse,
+}
+
 /// Accept or decline a crate owner invitation.
 #[utoipa::path(
     put,
@@ -341,13 +345,13 @@ pub struct OwnerInvitation {
         ("cookie" = []),
     ),
     tag = "owners",
-    responses((status = 200, description = "Successful Response")),
+    responses((status = 200, description = "Successful Response", body = inline(HandleResponse))),
 )]
 pub async fn handle_crate_owner_invitation(
     state: AppState,
     parts: Parts,
     Json(crate_invite): Json<OwnerInvitation>,
-) -> AppResult<ErasedJson> {
+) -> AppResult<Json<HandleResponse>> {
     let crate_invite = crate_invite.crate_owner_invite;
 
     let mut conn = state.db_write().await?;
@@ -364,7 +368,9 @@ pub async fn handle_crate_owner_invitation(
         invitation.decline(&mut conn).await?;
     }
 
-    Ok(json!({ "crate_owner_invitation": crate_invite }))
+    Ok(Json(HandleResponse {
+        crate_owner_invitation: crate_invite,
+    }))
 }
 
 /// Accept a crate owner invitation with a token.
@@ -375,23 +381,25 @@ pub async fn handle_crate_owner_invitation(
         ("token" = String, Path, description = "Secret token sent to the user's email address"),
     ),
     tag = "owners",
-    responses((status = 200, description = "Successful Response")),
+    responses((status = 200, description = "Successful Response", body = inline(HandleResponse))),
 )]
 pub async fn accept_crate_owner_invitation_with_token(
     state: AppState,
     Path(token): Path<String>,
-) -> AppResult<ErasedJson> {
+) -> AppResult<Json<HandleResponse>> {
     let mut conn = state.db_write().await?;
     let invitation = CrateOwnerInvitation::find_by_token(&token, &mut conn).await?;
 
     let crate_id = invitation.crate_id;
     invitation.accept(&mut conn).await?;
 
-    Ok(json!({
-        "crate_owner_invitation": {
-            "crate_id": crate_id,
-            "accepted": true,
-        },
+    let crate_owner_invitation = InvitationResponse {
+        crate_id,
+        accepted: true,
+    };
+
+    Ok(Json(HandleResponse {
+        crate_owner_invitation,
     }))
 }
 

src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap

@@ -3288,6 +3288,38 @@ expression: response.json()
         ],
         "responses": {
           "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "crate_owner_invitation": {
+                      "properties": {
+                        "accepted": {
+                          "description": "Whether the invitation was accepted.",
+                          "example": true,
+                          "type": "boolean"
+                        },
+                        "crate_id": {
+                          "description": "The opaque identifier for the crate this invitation is for.",
+                          "example": 42,
+                          "format": "int32",
+                          "type": "integer"
+                        }
+                      },
+                      "required": [
+                        "crate_id",
+                        "accepted"
+                      ],
+                      "type": "object"
+                    }
+                  },
+                  "required": [
+                    "crate_owner_invitation"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
             "description": "Successful Response"
           }
         },
@@ -3314,6 +3346,38 @@ expression: response.json()
         ],
         "responses": {
           "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "crate_owner_invitation": {
+                      "properties": {
+                        "accepted": {
+                          "description": "Whether the invitation was accepted.",
+                          "example": true,
+                          "type": "boolean"
+                        },
+                        "crate_id": {
+                          "description": "The opaque identifier for the crate this invitation is for.",
+                          "example": 42,
+                          "format": "int32",
+                          "type": "integer"
+                        }
+                      },
+                      "required": [
+                        "crate_id",
+                        "accepted"
+                      ],
+                      "type": "object"
+                    }
+                  },
+                  "required": [
+                    "crate_owner_invitation"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
             "description": "Successful Response"
           }
         },

src/views.rs

@@ -128,9 +128,14 @@ pub struct EncodableCrateOwnerInvitation {
     pub expires_at: DateTime<Utc>,
 }
 
-#[derive(Deserialize, Serialize, Debug, Copy, Clone)]
+#[derive(Deserialize, Serialize, Debug, Copy, Clone, utoipa::ToSchema)]
 pub struct InvitationResponse {
+    /// The opaque identifier for the crate this invitation is for.
+    #[schema(example = 42)]
     pub crate_id: i32,
+
+    /// Whether the invitation was accepted.
+    #[schema(example = true)]
     pub accepted: bool,
 }