Improve OpenAPI documentation for GET /api/v1/crates/{name}/owners endpoints

Author: Turbo87

src/controllers/krate/owners.rs

@@ -26,27 +26,37 @@ use oauth2::AccessToken;
 use secrecy::{ExposeSecret, SecretString};
 use thiserror::Error;
 
+#[derive(Debug, Serialize, utoipa::ToSchema)]
+pub struct UsersResponse {
+    pub users: Vec<EncodableOwner>,
+}
+
 /// List crate owners.
 #[utoipa::path(
     get,
     path = "/api/v1/crates/{name}/owners",
     params(CratePath),
     tag = "owners",
-    responses((status = 200, description = "Successful Response")),
+    responses((status = 200, description = "Successful Response", body = inline(UsersResponse))),
 )]
-pub async fn list_owners(state: AppState, path: CratePath) -> AppResult<ErasedJson> {
+pub async fn list_owners(state: AppState, path: CratePath) -> AppResult<Json<UsersResponse>> {
     let mut conn = state.db_read().await?;
 
     let krate = path.load_crate(&mut conn).await?;
 
-    let owners = krate
+    let users = krate
         .owners(&mut conn)
         .await?
         .into_iter()
         .map(Owner::into)
         .collect::<Vec<EncodableOwner>>();
 
-    Ok(json!({ "users": owners }))
+    Ok(Json(UsersResponse { users }))
+}
+
+#[derive(Debug, Serialize, utoipa::ToSchema)]
+pub struct TeamsResponse {
+    pub teams: Vec<EncodableOwner>,
 }
 
 /// List team owners of a crate.
@@ -55,19 +65,19 @@ pub async fn list_owners(state: AppState, path: CratePath) -> AppResult<ErasedJs
     path = "/api/v1/crates/{name}/owner_team",
     params(CratePath),
     tag = "owners",
-    responses((status = 200, description = "Successful Response")),
+    responses((status = 200, description = "Successful Response", body = inline(TeamsResponse))),
 )]
-pub async fn get_team_owners(state: AppState, path: CratePath) -> AppResult<ErasedJson> {
+pub async fn get_team_owners(state: AppState, path: CratePath) -> AppResult<Json<TeamsResponse>> {
     let mut conn = state.db_read().await?;
     let krate = path.load_crate(&mut conn).await?;
 
-    let owners = Team::owning(&krate, &mut conn)
+    let teams = Team::owning(&krate, &mut conn)
         .await?
         .into_iter()
         .map(Owner::into)
         .collect::<Vec<EncodableOwner>>();
 
-    Ok(json!({ "teams": owners }))
+    Ok(Json(TeamsResponse { teams }))
 }
 
 /// List user owners of a crate.
@@ -76,20 +86,20 @@ pub async fn get_team_owners(state: AppState, path: CratePath) -> AppResult<Eras
     path = "/api/v1/crates/{name}/owner_user",
     params(CratePath),
     tag = "owners",
-    responses((status = 200, description = "Successful Response")),
+    responses((status = 200, description = "Successful Response", body = inline(UsersResponse))),
 )]
-pub async fn get_user_owners(state: AppState, path: CratePath) -> AppResult<ErasedJson> {
+pub async fn get_user_owners(state: AppState, path: CratePath) -> AppResult<Json<UsersResponse>> {
     let mut conn = state.db_read().await?;
 
     let krate = path.load_crate(&mut conn).await?;
 
-    let owners = User::owning(&krate, &mut conn)
+    let users = User::owning(&krate, &mut conn)
         .await?
         .into_iter()
         .map(Owner::into)
         .collect::<Vec<EncodableOwner>>();
 
-    Ok(json!({ "users": owners }))
+    Ok(Json(UsersResponse { users }))
 }
 
 /// Add crate owners.

src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap

@@ -584,6 +584,56 @@ expression: response.json()
         ],
         "type": "object"
       },
+      "Owner": {
+        "properties": {
+          "avatar": {
+            "description": "The avatar URL of the team or user.",
+            "example": "https://avatars2.githubusercontent.com/u/1234567?v=4",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "id": {
+            "description": "The opaque identifier for the team or user, depending on the `kind` field.",
+            "example": 42,
+            "format": "int32",
+            "type": "integer"
+          },
+          "kind": {
+            "description": "The kind of the owner (`user` or `team`).",
+            "example": "user",
+            "type": "string"
+          },
+          "login": {
+            "description": "The login name of the team or user.",
+            "example": "ghost",
+            "type": "string"
+          },
+          "name": {
+            "description": "The display name of the team or user.",
+            "example": "Kate Morgan",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "url": {
+            "description": "The URL to the owner's profile.",
+            "example": "https://github.com/ghost",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "id",
+          "login",
+          "kind"
+        ],
+        "type": "object"
+      },
       "Slug": {
         "properties": {
           "description": {
@@ -1952,6 +2002,24 @@ expression: response.json()
         ],
         "responses": {
           "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "teams": {
+                      "items": {
+                        "$ref": "#/components/schemas/Owner"
+                      },
+                      "type": "array"
+                    }
+                  },
+                  "required": [
+                    "teams"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
             "description": "Successful Response"
           }
         },
@@ -1977,6 +2045,24 @@ expression: response.json()
         ],
         "responses": {
           "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "users": {
+                      "items": {
+                        "$ref": "#/components/schemas/Owner"
+                      },
+                      "type": "array"
+                    }
+                  },
+                  "required": [
+                    "users"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
             "description": "Successful Response"
           }
         },
@@ -2033,6 +2119,24 @@ expression: response.json()
         ],
         "responses": {
           "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "users": {
+                      "items": {
+                        "$ref": "#/components/schemas/Owner"
+                      },
+                      "type": "array"
+                    }
+                  },
+                  "required": [
+                    "users"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
             "description": "Successful Response"
           }
         },

src/views.rs

@@ -509,13 +509,31 @@ pub struct EncodableCrateLinks {
     pub reverse_dependencies: String,
 }
 
-#[derive(Serialize, Deserialize, Debug)]
+#[derive(Serialize, Deserialize, Debug, utoipa::ToSchema)]
+#[schema(as = Owner)]
 pub struct EncodableOwner {
+    /// The opaque identifier for the team or user, depending on the `kind` field.
+    #[schema(example = 42)]
     pub id: i32,
+
+    /// The login name of the team or user.
+    #[schema(example = "ghost")]
     pub login: String,
+
+    /// The kind of the owner (`user` or `team`).
+    #[schema(example = "user")]
     pub kind: String,
+
+    /// The URL to the owner's profile.
+    #[schema(example = "https://github.com/ghost")]
     pub url: Option<String>,
+
+    /// The display name of the team or user.
+    #[schema(example = "Kate Morgan")]
     pub name: Option<String>,
+
+    /// The avatar URL of the team or user.
+    #[schema(example = "https://avatars2.githubusercontent.com/u/1234567?v=4")]
     pub avatar: Option<String>,
 }