Skip to content

Commit 2f26194

Browse files
Turbo87Turbo87
authored
Add OpenAPI documentation for GET /api/v1/me response payload (#10707)
1 parent 0e96e97 commit 2f26194

File tree

3 files changed

+167
-7
lines changed

3 files changed

+167
-7
lines changed

‎src/controllers/user/me.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ use crate::views::{EncodableMe, EncodablePrivateUser, EncodableVersion, OwnedCra
2121
path = "/api/v1/me",
2222
security(("cookie" = [])),
2323
tag = "users",
24-
responses((status = 200, description = "Successful Response")),
24+
responses((status = 200, description = "Successful Response", body = inline(EncodableMe))),
2525
)]
2626
pub async fn get_authenticated_user(app: AppState, req: Parts) -> AppResult<Json<EncodableMe>> {
2727
let mut conn = app.db_read_prefer_primary().await?;

‎src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,82 @@ expression: response.json()
55
{
66
"components": {
77
"schemas": {
8+
"AuthenticatedUser": {
9+
"properties": {
10+
"avatar": {
11+
"description": "The user's avatar URL, if set.",
12+
"example": "https://avatars2.githubusercontent.com/u/1234567?v=4",
13+
"type": [
14+
"string",
15+
"null"
16+
]
17+
},
18+
"email": {
19+
"description": "The user's email address, if set.",
20+
"example": "[email protected]",
21+
"type": [
22+
"string",
23+
"null"
24+
]
25+
},
26+
"email_verification_sent": {
27+
"description": "Whether the user's email address verification email has been sent.",
28+
"example": true,
29+
"type": "boolean"
30+
},
31+
"email_verified": {
32+
"description": "Whether the user's email address has been verified.",
33+
"example": true,
34+
"type": "boolean"
35+
},
36+
"id": {
37+
"description": "An opaque identifier for the user.",
38+
"example": 42,
39+
"format": "int32",
40+
"type": "integer"
41+
},
42+
"is_admin": {
43+
"description": "Whether the user is a crates.io administrator.",
44+
"example": false,
45+
"type": "boolean"
46+
},
47+
"login": {
48+
"description": "The user's login name.",
49+
"example": "ghost",
50+
"type": "string"
51+
},
52+
"name": {
53+
"description": "The user's display name, if set.",
54+
"example": "Kate Morgan",
55+
"type": [
56+
"string",
57+
"null"
58+
]
59+
},
60+
"publish_notifications": {
61+
"description": "Whether the user has opted in to receive publish notifications via email.",
62+
"example": true,
63+
"type": "boolean"
64+
},
65+
"url": {
66+
"description": "The user's GitHub profile URL.",
67+
"example": "https://github.com/ghost",
68+
"type": [
69+
"string",
70+
"null"
71+
]
72+
}
73+
},
74+
"required": [
75+
"id",
76+
"login",
77+
"email_verified",
78+
"email_verification_sent",
79+
"is_admin",
80+
"publish_notifications"
81+
],
82+
"type": "object"
83+
},
884
"Category": {
985
"properties": {
1086
"category": {
@@ -1879,6 +1955,52 @@ expression: response.json()
18791955
"operationId": "get_authenticated_user",
18801956
"responses": {
18811957
"200": {
1958+
"content": {
1959+
"application/json": {
1960+
"schema": {
1961+
"properties": {
1962+
"owned_crates": {
1963+
"description": "The crates that the authenticated user owns.",
1964+
"items": {
1965+
"properties": {
1966+
"email_notifications": {
1967+
"deprecated": true,
1968+
"type": "boolean"
1969+
},
1970+
"id": {
1971+
"description": "The opaque identifier of the crate.",
1972+
"example": 123,
1973+
"format": "int32",
1974+
"type": "integer"
1975+
},
1976+
"name": {
1977+
"description": "The name of the crate.",
1978+
"example": "serde",
1979+
"type": "string"
1980+
}
1981+
},
1982+
"required": [
1983+
"id",
1984+
"name",
1985+
"email_notifications"
1986+
],
1987+
"type": "object"
1988+
},
1989+
"type": "array"
1990+
},
1991+
"user": {
1992+
"$ref": "#/components/schemas/AuthenticatedUser",
1993+
"description": "The authenticated user."
1994+
}
1995+
},
1996+
"required": [
1997+
"user",
1998+
"owned_crates"
1999+
],
2000+
"type": "object"
2001+
}
2002+
}
2003+
},
18822004
"description": "Successful Response"
18832005
}
18842006
},

‎src/views.rs‎

Lines changed: 44 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -485,33 +485,71 @@ pub struct EncodableApiTokenWithToken {
485485
pub plaintext: String,
486486
}
487487

488-
#[derive(Deserialize, Serialize, Debug)]
488+
#[derive(Deserialize, Serialize, Debug, utoipa::ToSchema)]
489489
pub struct OwnedCrate {
490+
/// The opaque identifier of the crate.
491+
#[schema(example = 123)]
490492
pub id: i32,
493+
494+
/// The name of the crate.
495+
#[schema(example = "serde")]
491496
pub name: String,
497+
498+
#[schema(deprecated)]
492499
pub email_notifications: bool,
493500
}
494501

495-
#[derive(Serialize, Deserialize, Debug)]
502+
#[derive(Serialize, Deserialize, Debug, utoipa::ToSchema)]
496503
pub struct EncodableMe {
504+
/// The authenticated user.
497505
pub user: EncodablePrivateUser,
506+
507+
/// The crates that the authenticated user owns.
508+
#[schema(inline)]
498509
pub owned_crates: Vec<OwnedCrate>,
499510
}
500511

501-
/// The serialization format for the `User` model.
502-
/// Same as public user, except for addition of
503-
/// email field
504-
#[derive(Deserialize, Serialize, Debug)]
512+
#[derive(Deserialize, Serialize, Debug, utoipa::ToSchema)]
513+
#[schema(as = AuthenticatedUser)]
505514
pub struct EncodablePrivateUser {
515+
/// An opaque identifier for the user.
516+
#[schema(example = 42)]
506517
pub id: i32,
518+
519+
/// The user's login name.
520+
#[schema(example = "ghost")]
507521
pub login: String,
522+
523+
/// Whether the user's email address has been verified.
524+
#[schema(example = true)]
508525
pub email_verified: bool,
526+
527+
/// Whether the user's email address verification email has been sent.
528+
#[schema(example = true)]
509529
pub email_verification_sent: bool,
530+
531+
/// The user's display name, if set.
532+
#[schema(example = "Kate Morgan")]
510533
pub name: Option<String>,
534+
535+
/// The user's email address, if set.
536+
#[schema(example = "[email protected]")]
511537
pub email: Option<String>,
538+
539+
/// The user's avatar URL, if set.
540+
#[schema(example = "https://avatars2.githubusercontent.com/u/1234567?v=4")]
512541
pub avatar: Option<String>,
542+
543+
/// The user's GitHub profile URL.
544+
#[schema(example = "https://github.com/ghost")]
513545
pub url: Option<String>,
546+
547+
/// Whether the user is a crates.io administrator.
548+
#[schema(example = false)]
514549
pub is_admin: bool,
550+
551+
/// Whether the user has opted in to receive publish notifications via email.
552+
#[schema(example = true)]
515553
pub publish_notifications: bool,
516554
}
517555

0 commit comments

Comments
 (0)