Add OpenAPI documentation for GET /api/v1/me/crate_owner_invitations response payload

Author: Turbo87

src/controllers/crate_owner_invitation.rs

@@ -26,18 +26,27 @@ use http::request::Parts;
 use indexmap::IndexMap;
 use std::collections::{HashMap, HashSet};
 
+#[derive(Serialize, utoipa::ToSchema)]
+pub struct LegacyListResponse {
+    /// The list of crate owner invitations.
+    crate_owner_invitations: Vec<EncodableCrateOwnerInvitationV1>,
+
+    /// The list of users referenced in the crate owner invitations.
+    users: Vec<EncodablePublicUser>,
+}
+
 /// List all crate owner invitations for the authenticated user.
 #[utoipa::path(
     get,
     path = "/api/v1/me/crate_owner_invitations",
     security(("cookie" = [])),
     tag = "owners",
-    responses((status = 200, description = "Successful Response")),
+    responses((status = 200, description = "Successful Response", body = inline(LegacyListResponse))),
 )]
 pub async fn list_crate_owner_invitations_for_user(
     app: AppState,
     req: Parts,
-) -> AppResult<ErasedJson> {
+) -> AppResult<Json<LegacyListResponse>> {
     let mut conn = app.db_read().await?;
     let auth = AuthCheck::only_cookie().check(&req, &mut conn).await?;
 
@@ -68,9 +77,9 @@ pub async fn list_crate_owner_invitations_for_user(
         })
         .collect::<AppResult<Vec<EncodableCrateOwnerInvitationV1>>>()?;
 
-    Ok(json!({
-        "crate_owner_invitations": crate_owner_invitations,
-        "users": users,
+    Ok(Json(LegacyListResponse {
+        crate_owner_invitations,
+        users,
     }))
 }
 

src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap

@@ -153,6 +153,60 @@ expression: response.json()
         ],
         "type": "object"
       },
+      "LegacyCrateOwnerInvitation": {
+        "properties": {
+          "crate_id": {
+            "description": "The ID of the crate that the user was invited to be an owner of.",
+            "example": 123,
+            "format": "int32",
+            "type": "integer"
+          },
+          "crate_name": {
+            "description": "The name of the crate that the user was invited to be an owner of.",
+            "example": "serde",
+            "type": "string"
+          },
+          "created_at": {
+            "description": "The date and time this invitation was created.",
+            "example": "2019-12-13T13:46:41Z",
+            "format": "date-time",
+            "type": "string"
+          },
+          "expires_at": {
+            "description": "The date and time this invitation will expire.",
+            "example": "2020-01-13T13:46:41Z",
+            "format": "date-time",
+            "type": "string"
+          },
+          "invited_by_username": {
+            "description": "The username of the user who sent the invitation.",
+            "example": "ghost",
+            "type": "string"
+          },
+          "invitee_id": {
+            "description": "The ID of the user who was invited to be a crate owner.",
+            "example": 42,
+            "format": "int32",
+            "type": "integer"
+          },
+          "inviter_id": {
+            "description": "The ID of the user who sent the invitation.",
+            "example": 3,
+            "format": "int32",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "invitee_id",
+          "inviter_id",
+          "invited_by_username",
+          "crate_name",
+          "crate_id",
+          "created_at",
+          "expires_at"
+        ],
+        "type": "object"
+      },
       "Slug": {
         "properties": {
           "description": {
@@ -1764,6 +1818,33 @@ expression: response.json()
         "operationId": "list_crate_owner_invitations_for_user",
         "responses": {
           "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "crate_owner_invitations": {
+                      "description": "The list of crate owner invitations.",
+                      "items": {
+                        "$ref": "#/components/schemas/LegacyCrateOwnerInvitation"
+                      },
+                      "type": "array"
+                    },
+                    "users": {
+                      "description": "The list of users referenced in the crate owner invitations.",
+                      "items": {
+                        "$ref": "#/components/schemas/User"
+                      },
+                      "type": "array"
+                    }
+                  },
+                  "required": [
+                    "crate_owner_invitations",
+                    "users"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
             "description": "Successful Response"
           }
         },

src/views.rs

@@ -79,15 +79,29 @@ impl From<Category> for EncodableCategory {
     }
 }
 
-/// The serialization format for the `CrateOwnerInvitation` model.
-#[derive(Deserialize, Serialize, Debug, PartialEq, Eq)]
+#[derive(Deserialize, Serialize, Debug, PartialEq, Eq, utoipa::ToSchema)]
+#[schema(as = LegacyCrateOwnerInvitation)]
 pub struct EncodableCrateOwnerInvitationV1 {
+    /// The ID of the user who was invited to be a crate owner.
+    #[schema(example = 42)]
     pub invitee_id: i32,
+    /// The ID of the user who sent the invitation.
+    #[schema(example = 3)]
     pub inviter_id: i32,
+    /// The username of the user who sent the invitation.
+    #[schema(example = "ghost")]
     pub invited_by_username: String,
+    /// The name of the crate that the user was invited to be an owner of.
+    #[schema(example = "serde")]
     pub crate_name: String,
+    /// The ID of the crate that the user was invited to be an owner of.
+    #[schema(example = 123)]
     pub crate_id: i32,
+    /// The date and time this invitation was created.
+    #[schema(example = "2019-12-13T13:46:41Z")]
     pub created_at: DateTime<Utc>,
+    /// The date and time this invitation will expire.
+    #[schema(example = "2020-01-13T13:46:41Z")]
     pub expires_at: DateTime<Utc>,
 }