Improve OpenAPI documentation for PUT /api/v1/me/tokens endpoint

Author: Turbo87

src/controllers/token.rs

@@ -89,19 +89,24 @@ pub struct NewApiTokenRequest {
     api_token: NewApiToken,
 }
 
+#[derive(Debug, Serialize, utoipa::ToSchema)]
+pub struct CreateResponse {
+    api_token: EncodableApiTokenWithToken,
+}
+
 /// Create a new API token.
 #[utoipa::path(
     put,
     path = "/api/v1/me/tokens",
     security(("cookie" = [])),
     tag = "api_tokens",
-    responses((status = 200, description = "Successful Response")),
+    responses((status = 200, description = "Successful Response", body = inline(CreateResponse))),
 )]
 pub async fn create_api_token(
     app: AppState,
     parts: Parts,
     Json(new): Json<NewApiTokenRequest>,
-) -> AppResult<ErasedJson> {
+) -> AppResult<Json<CreateResponse>> {
     if new.api_token.name.is_empty() {
         return Err(bad_request("name must have a value"));
     }
@@ -186,7 +191,7 @@ pub async fn create_api_token(
         plaintext: plaintext.expose_secret().to_string(),
     };
 
-    Ok(json!({ "api_token": api_token }))
+    Ok(Json(CreateResponse { api_token }))
 }
 
 /// Find API token by id.

src/snapshots/crates_io__openapi__tests__openapi_snapshot.snap

@@ -497,6 +497,26 @@ expression: response.json()
         ],
         "type": "object"
       },
+      "EncodableApiTokenWithToken": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/ApiToken"
+          },
+          {
+            "properties": {
+              "token": {
+                "description": "The plaintext API token.\n\nOnly available when the token is created.",
+                "example": "a1b2c3d4e5f6g7h8i9j0",
+                "type": "string"
+              }
+            },
+            "required": [
+              "token"
+            ],
+            "type": "object"
+          }
+        ]
+      },
       "EncodableDependency": {
         "properties": {
           "crate_id": {
@@ -3667,6 +3687,21 @@ expression: response.json()
         "operationId": "create_api_token",
         "responses": {
           "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "api_token": {
+                      "$ref": "#/components/schemas/EncodableApiTokenWithToken"
+                    }
+                  },
+                  "required": [
+                    "api_token"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
             "description": "Successful Response"
           }
         },

src/views.rs

@@ -628,14 +628,16 @@ impl From<Team> for EncodableTeam {
     }
 }
 
-/// The serialization format for the `ApiToken` model with its token value.
-/// This should only be used when initially creating a new token to minimize
-/// the chance of token leaks.
-#[derive(Serialize, Debug)]
+#[derive(Serialize, Debug, utoipa::ToSchema)]
 pub struct EncodableApiTokenWithToken {
     #[serde(flatten)]
     pub token: ApiToken,
+
+    /// The plaintext API token.
+    ///
+    /// Only available when the token is created.
     #[serde(rename = "token")]
+    #[schema(example = "a1b2c3d4e5f6g7h8i9j0")]
     pub plaintext: String,
 }