Improve OpenAPI documentation for PUT /api/v1/crates/new endpoint

Author: Turbo87

src/controllers/krate/publish.rs

@@ -63,7 +63,7 @@ const MAX_DESCRIPTION_LENGTH: usize = 1000;
         ("cookie" = []),
     ),
     tag = "publish",
-    responses((status = 200, description = "Successful Response")),
+    responses((status = 200, description = "Successful Response", body = inline(GoodCrate))),
 )]
 pub async fn publish(app: AppState, req: Parts, body: Body) -> AppResult<Json<GoodCrate>> {
     let stream = body.into_data_stream();

src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap

@@ -634,6 +634,38 @@ expression: response.json()
         ],
         "type": "object"
       },
+      "PublishWarnings": {
+        "properties": {
+          "invalid_badges": {
+            "deprecated": true,
+            "example": [],
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "invalid_categories": {
+            "example": [],
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "other": {
+            "example": [],
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "invalid_categories",
+          "invalid_badges",
+          "other"
+        ],
+        "type": "object"
+      },
       "Slug": {
         "properties": {
           "description": {
@@ -1611,6 +1643,25 @@ expression: response.json()
         "operationId": "publish",
         "responses": {
           "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "crate": {
+                      "$ref": "#/components/schemas/Crate"
+                    },
+                    "warnings": {
+                      "$ref": "#/components/schemas/PublishWarnings"
+                    }
+                  },
+                  "required": [
+                    "crate",
+                    "warnings"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
             "description": "Successful Response"
           }
         },

src/views.rs

@@ -983,17 +983,20 @@ pub struct EncodableVersionLinks {
     pub authors: String,
 }
 
-#[derive(Serialize, Deserialize, Debug)]
+#[derive(Serialize, Deserialize, Debug, utoipa::ToSchema)]
 pub struct GoodCrate {
     #[serde(rename = "crate")]
     pub krate: EncodableCrate,
     pub warnings: PublishWarnings,
 }
 
-#[derive(Serialize, Deserialize, Debug)]
+#[derive(Serialize, Deserialize, Debug, utoipa::ToSchema)]
 pub struct PublishWarnings {
+    #[schema(example = json!([]))]
     pub invalid_categories: Vec<String>,
+    #[schema(deprecated, example = json!([]))]
     pub invalid_badges: Vec<String>,
+    #[schema(example = json!([]))]
     pub other: Vec<String>,
 }