Skip to content

Add OpenAPI documentation for crate_owner_invitation response payloads #10703

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 27, 2025
Merged

Add OpenAPI documentation for crate_owner_invitation response payloads #10703

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
44d9a8b
Add OpenAPI documentation for `GET /api/private/crate_owner_invitatio…
Turbo87 Feb 26, 2025
c7a329b
Add OpenAPI documentation for `GET /api/v1/me/crate_owner_invitations…
Turbo87 Feb 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 24 additions & 8 deletions src/controllers/crate_owner_invitation.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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?;

Expand Down Expand Up @@ -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,
}))
}

Expand All @@ -96,7 +105,7 @@ pub struct ListQueryParams {
params(ListQueryParams, PaginationQueryParams),
security(("cookie" = [])),
tag = "owners",
responses((status = 200, description = "Successful Response")),
responses((status = 200, description = "Successful Response", body = inline(PrivateListResponse))),
)]
pub async fn list_crate_owner_invitations(
app: AppState,
Expand Down Expand Up @@ -296,15 +305,22 @@ async fn prepare_list(
})
}

#[derive(Serialize)]
#[derive(Serialize, utoipa::ToSchema)]
pub struct PrivateListResponse {
/// The list of crate owner invitations.
invitations: Vec<EncodableCrateOwnerInvitation>,

/// The list of users referenced in the crate owner invitations.
users: Vec<EncodablePublicUser>,

#[schema(inline)]
meta: ResponseMeta,
}

#[derive(Serialize)]
#[derive(Serialize, utoipa::ToSchema)]
struct ResponseMeta {
/// Query parameter string to fetch the next page of results.
#[schema(example = "?seek=c0ffee")]
next_page: Option<String>,
}

Expand Down
170 changes: 170 additions & 0 deletions src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,54 @@ expression: response.json()
],
"type": "object"
},
"CrateOwnerInvitation": {
"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"
},
"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",
"crate_id",
"crate_name",
"created_at",
"expires_at"
],
"type": "object"
},
"Keyword": {
"properties": {
"crates_cnt": {
Expand Down Expand Up @@ -105,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": {
Expand Down Expand Up @@ -261,6 +363,47 @@ expression: response.json()
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"invitations": {
"description": "The list of crate owner invitations.",
"items": {
"$ref": "#/components/schemas/CrateOwnerInvitation"
},
"type": "array"
},
"meta": {
"properties": {
"next_page": {
"description": "Query parameter string to fetch the next page of results.",
"example": "?seek=c0ffee",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"users": {
"description": "The list of users referenced in the crate owner invitations.",
"items": {
"$ref": "#/components/schemas/User"
},
"type": "array"
}
},
"required": [
"invitations",
"users",
"meta"
],
"type": "object"
}
}
},
"description": "Successful Response"
}
},
Expand Down Expand Up @@ -1675,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"
}
},
Expand Down
33 changes: 30 additions & 3 deletions src/views.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,25 +79,52 @@ 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>,
}

#[derive(Deserialize, Serialize, Debug, PartialEq, Eq)]
#[derive(Deserialize, Serialize, Debug, PartialEq, Eq, utoipa::ToSchema)]
#[schema(as = CrateOwnerInvitation)]
pub struct EncodableCrateOwnerInvitation {
/// 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 ID of the crate that the user was invited to be an owner of.
#[schema(example = 123)]
pub crate_id: i32,
/// The name of the crate that the user was invited to be an owner of.
#[schema(example = "serde")]
pub crate_name: String,
/// 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>,
}

Expand Down