Improve OpenAPI documentation for GET /api/v1/site_metadata endpoint

Author: Turbo87

src/controllers/site_metadata.rs

@@ -1,6 +1,20 @@
 use crate::app::AppState;
+use axum::Json;
 use axum::response::IntoResponse;
-use axum_extra::json;
+
+#[derive(Debug, Serialize, utoipa::ToSchema)]
+pub struct MetadataResponse<'a> {
+    /// The SHA1 of the currently deployed commit.
+    #[schema(example = "0aebe2cdfacae1229b93853b1c58f9352195f081")]
+    pub deployed_sha: &'a str,
+
+    /// The SHA1 of the currently deployed commit.
+    #[schema(example = "0aebe2cdfacae1229b93853b1c58f9352195f081")]
+    pub commit: &'a str,
+
+    /// Whether the crates.io service is in read-only mode.
+    pub read_only: bool,
+}
 
 /// Get crates.io metadata.
 ///
@@ -10,17 +24,18 @@ use axum_extra::json;
     get,
     path = "/api/v1/site_metadata",
     tag = "other",
-    responses((status = 200, description = "Successful Response")),
+    responses((status = 200, description = "Successful Response", body = inline(MetadataResponse<'_>))),
 )]
 pub async fn get_site_metadata(state: AppState) -> impl IntoResponse {
     let read_only = state.config.db.are_all_read_only();
 
     let deployed_sha =
         dotenvy::var("HEROKU_SLUG_COMMIT").unwrap_or_else(|_| String::from("unknown"));
 
-    json!({
-        "deployed_sha": &deployed_sha[..],
-        "commit": &deployed_sha[..],
-        "read_only": read_only,
+    Json(MetadataResponse {
+        deployed_sha: &deployed_sha,
+        commit: &deployed_sha,
+        read_only,
     })
+    .into_response()
 }

src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap

@@ -3661,6 +3661,34 @@ expression: response.json()
         "operationId": "get_site_metadata",
         "responses": {
           "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "commit": {
+                      "description": "The SHA1 of the currently deployed commit.",
+                      "example": "0aebe2cdfacae1229b93853b1c58f9352195f081",
+                      "type": "string"
+                    },
+                    "deployed_sha": {
+                      "description": "The SHA1 of the currently deployed commit.",
+                      "example": "0aebe2cdfacae1229b93853b1c58f9352195f081",
+                      "type": "string"
+                    },
+                    "read_only": {
+                      "description": "Whether the crates.io service is in read-only mode.",
+                      "type": "boolean"
+                    }
+                  },
+                  "required": [
+                    "deployed_sha",
+                    "commit",
+                    "read_only"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
             "description": "Successful Response"
           }
         },