Improve OpenAPI documentation for GET /api/v1/crates/{name}/{version}/readme endpoint

Author: Turbo87

src/controllers/version/readme.rs

@@ -1,23 +1,33 @@
 use crate::app::AppState;
 use crate::controllers::version::CrateVersionPath;
 use crate::util::{RequestUtils, redirect};
+use axum::Json;
 use axum::response::{IntoResponse, Response};
-use axum_extra::json;
 use http::request::Parts;
 
+#[derive(Debug, Serialize, utoipa::ToSchema)]
+pub struct UrlResponse {
+    /// The URL to the readme file.
+    #[schema(example = "https://static.crates.io/readmes/serde/serde-1.0.0.html")]
+    pub url: String,
+}
+
 /// Get the readme of a crate version.
 #[utoipa::path(
     get,
     path = "/api/v1/crates/{name}/{version}/readme",
     params(CrateVersionPath),
     tag = "versions",
-    responses((status = 200, description = "Successful Response")),
+    responses(
+        (status = 302, description = "Successful Response (default)", headers(("location" = String, description = "The URL to the readme file."))),
+        (status = 200, description = "Successful Response (for `content-type: application/json`)", body = inline(UrlResponse)),
+    ),
 )]
 pub async fn get_version_readme(app: AppState, path: CrateVersionPath, req: Parts) -> Response {
-    let redirect_url = app.storage.readme_location(&path.name, &path.version);
+    let url = app.storage.readme_location(&path.name, &path.version);
     if req.wants_json() {
-        json!({ "url": redirect_url }).into_response()
+        Json(UrlResponse { url }).into_response()
     } else {
-        redirect(redirect_url)
+        redirect(url)
     }
 }

src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap

@@ -2091,7 +2091,35 @@ expression: response.json()
         ],
         "responses": {
           "200": {
-            "description": "Successful Response"
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "url": {
+                      "description": "The URL to the readme file.",
+                      "example": "https://static.crates.io/readmes/serde/serde-1.0.0.html",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "url"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
+            "description": "Successful Response (for `content-type: application/json`)"
+          },
+          "302": {
+            "description": "Successful Response (default)",
+            "headers": {
+              "location": {
+                "description": "The URL to the readme file.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
           }
         },
         "summary": "Get the readme of a crate version.",