Improve OpenAPI documentation for GET /api/v1/teams/{team} endpoint (#10751)

Author: Turbo87

src/controllers/team.rs

@@ -2,12 +2,16 @@ use crate::app::AppState;
 use crate::models::Team;
 use crate::util::errors::AppResult;
 use crate::views::EncodableTeam;
+use axum::Json;
 use axum::extract::Path;
-use axum_extra::json;
-use axum_extra::response::ErasedJson;
 use diesel::prelude::*;
 use diesel_async::RunQueryDsl;
 
+#[derive(Debug, Serialize, utoipa::ToSchema)]
+pub struct GetResponse {
+    team: EncodableTeam,
+}
+
 /// Find team by login.
 #[utoipa::path(
     get,
@@ -16,12 +20,13 @@ use diesel_async::RunQueryDsl;
         ("team" = String, Path, description = "Name of the team", example = "github:rust-lang:crates-io"),
     ),
     tag = "teams",
-    responses((status = 200, description = "Successful Response")),
+    responses((status = 200, description = "Successful Response", body = inline(GetResponse))),
 )]
-pub async fn find_team(state: AppState, Path(name): Path<String>) -> AppResult<ErasedJson> {
+pub async fn find_team(state: AppState, Path(name): Path<String>) -> AppResult<Json<GetResponse>> {
     use crate::schema::teams::dsl::{login, teams};
 
     let mut conn = state.db_read().await?;
     let team: Team = teams.filter(login.eq(&name)).first(&mut conn).await?;
-    Ok(json!({ "team": EncodableTeam::from(team) }))
+    let team = EncodableTeam::from(team);
+    Ok(Json(GetResponse { team }))
 }

src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap

@@ -691,6 +691,50 @@ expression: response.json()
         ],
         "type": "object"
       },
+      "Team": {
+        "properties": {
+          "avatar": {
+            "description": "The avatar URL of the team.",
+            "example": "https://avatars2.githubusercontent.com/u/1234567?v=4",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "id": {
+            "description": "An opaque identifier for the team.",
+            "example": 42,
+            "format": "int32",
+            "type": "integer"
+          },
+          "login": {
+            "description": "The login name of the team.",
+            "example": "github:rust-lang:crates-io",
+            "type": "string"
+          },
+          "name": {
+            "description": "The display name of the team.",
+            "example": "Crates.io team",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "url": {
+            "description": "The GitHub profile URL of the team.",
+            "example": "https://github.com/rust-lang",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "id",
+          "login"
+        ],
+        "type": "object"
+      },
       "User": {
         "properties": {
           "avatar": {
@@ -3803,6 +3847,21 @@ expression: response.json()
         ],
         "responses": {
           "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "team": {
+                      "$ref": "#/components/schemas/Team"
+                    }
+                  },
+                  "required": [
+                    "team"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
             "description": "Successful Response"
           }
         },

src/views.rs

@@ -583,12 +583,27 @@ impl From<Owner> for EncodableOwner {
     }
 }
 
-#[derive(Serialize, Debug)]
+#[derive(Serialize, Debug, utoipa::ToSchema)]
+#[schema(as = Team)]
 pub struct EncodableTeam {
+    /// An opaque identifier for the team.
+    #[schema(example = 42)]
     pub id: i32,
+
+    /// The login name of the team.
+    #[schema(example = "github:rust-lang:crates-io")]
     pub login: String,
+
+    /// The display name of the team.
+    #[schema(example = "Crates.io team")]
     pub name: Option<String>,
+
+    /// The avatar URL of the team.
+    #[schema(example = "https://avatars2.githubusercontent.com/u/1234567?v=4")]
     pub avatar: Option<String>,
+
+    /// The GitHub profile URL of the team.
+    #[schema(example = "https://github.com/rust-lang")]
     pub url: Option<String>,
 }