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

Author: Turbo87

Cargo.lock

@@ -25,6 +25,7 @@ sha2 = "=0.10.8"
 thiserror = "=2.0.12"
 tracing = "=0.1.41"
 unicode-xid = "=0.2.6"
+utoipa = "=5.3.1"
 
 [dev-dependencies]
 claims = "=0.8.0"

crates/crates_io_database/Cargo.toml

@@ -39,21 +39,43 @@ impl NewApiToken {
 }
 
 /// The model representing a row in the `api_tokens` database table.
-#[derive(Debug, Identifiable, Queryable, Selectable, Associations, serde::Serialize)]
+#[derive(
+    Debug, Identifiable, Queryable, Selectable, Associations, serde::Serialize, utoipa::ToSchema,
+)]
 #[diesel(belongs_to(User))]
 pub struct ApiToken {
+    /// An opaque unique identifier for the token.
+    #[schema(example = 42)]
     pub id: i32,
+
     #[serde(skip)]
     pub user_id: i32,
+
+    /// The name of the token.
+    #[schema(example = "Example API Token")]
     pub name: String,
+
+    /// The date and time when the token was created.
+    #[schema(example = "2017-01-06T14:23:11Z")]
     pub created_at: DateTime<Utc>,
+
+    /// The date and time when the token was last used.
+    #[schema(example = "2021-10-26T11:32:12Z")]
     pub last_used_at: Option<DateTime<Utc>>,
+
     #[serde(skip)]
     pub revoked: bool,
-    /// `None` or a list of crate scope patterns (see RFC #2947)
+
+    /// `None` or a list of crate scope patterns (see RFC #2947).
+    #[schema(value_type = Option<Vec<String>>, example = json!(["serde"]))]
     pub crate_scopes: Option<Vec<CrateScope>>,
-    /// A list of endpoint scopes or `None` for the `legacy` endpoint scope (see RFC #2947)
+
+    /// A list of endpoint scopes or `None` for the `legacy` endpoint scope (see RFC #2947).
+    #[schema(example = json!(["publish-update"]))]
     pub endpoint_scopes: Option<Vec<EndpointScope>>,
+
+    /// The date and time when the token will expire, or `null`.
+    #[schema(example = "2030-10-26T11:32:12Z")]
     pub expired_at: Option<DateTime<Utc>>,
 }
 

crates/crates_io_database/src/models/token.rs

@@ -5,7 +5,9 @@ use diesel::serialize::{self, IsNull, Output, ToSql};
 use diesel::sql_types::Text;
 use std::io::Write;
 
-#[derive(Clone, Copy, Debug, PartialEq, Eq, diesel::AsExpression, serde::Serialize)]
+#[derive(
+    Clone, Copy, Debug, PartialEq, Eq, diesel::AsExpression, serde::Serialize, utoipa::ToSchema,
+)]
 #[diesel(sql_type = Text)]
 #[serde(rename_all = "kebab-case")]
 pub enum EndpointScope {

crates/crates_io_database/src/models/token/scopes.rs

@@ -37,13 +37,18 @@ impl GetParams {
     }
 }
 
+#[derive(Debug, Serialize, utoipa::ToSchema)]
+pub struct ListResponse {
+    pub api_tokens: Vec<ApiToken>,
+}
+
 /// List all API tokens of the authenticated user.
 #[utoipa::path(
     get,
     path = "/api/v1/me/tokens",
     security(("cookie" = [])),
     tag = "api_tokens",
-    responses((status = 200, description = "Successful Response")),
+    responses((status = 200, description = "Successful Response", body = inline(ListResponse))),
 )]
 pub async fn list_api_tokens(
     app: AppState,

src/controllers/token.rs

@@ -5,6 +5,78 @@ expression: response.json()
 {
   "components": {
     "schemas": {
+      "ApiToken": {
+        "description": "The model representing a row in the `api_tokens` database table.",
+        "properties": {
+          "crate_scopes": {
+            "description": "`None` or a list of crate scope patterns (see RFC #2947).",
+            "example": [
+              "serde"
+            ],
+            "items": {
+              "type": "string"
+            },
+            "type": [
+              "array",
+              "null"
+            ]
+          },
+          "created_at": {
+            "description": "The date and time when the token was created.",
+            "example": "2017-01-06T14:23:11Z",
+            "format": "date-time",
+            "type": "string"
+          },
+          "endpoint_scopes": {
+            "description": "A list of endpoint scopes or `None` for the `legacy` endpoint scope (see RFC #2947).",
+            "example": [
+              "publish-update"
+            ],
+            "items": {
+              "$ref": "#/components/schemas/EndpointScope"
+            },
+            "type": [
+              "array",
+              "null"
+            ]
+          },
+          "expired_at": {
+            "description": "The date and time when the token will expire, or `null`.",
+            "example": "2030-10-26T11:32:12Z",
+            "format": "date-time",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "id": {
+            "description": "An opaque unique identifier for the token.",
+            "example": 42,
+            "format": "int32",
+            "type": "integer"
+          },
+          "last_used_at": {
+            "description": "The date and time when the token was last used.",
+            "example": "2021-10-26T11:32:12Z",
+            "format": "date-time",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "name": {
+            "description": "The name of the token.",
+            "example": "Example API Token",
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "created_at"
+        ],
+        "type": "object"
+      },
       "AuthenticatedUser": {
         "properties": {
           "avatar": {
@@ -497,6 +569,15 @@ expression: response.json()
         ],
         "type": "object"
       },
+      "EndpointScope": {
+        "enum": [
+          "publish-new",
+          "publish-update",
+          "yank",
+          "change-owners"
+        ],
+        "type": "string"
+      },
       "Keyword": {
         "properties": {
           "crates_cnt": {
@@ -3551,6 +3632,24 @@ expression: response.json()
         "operationId": "list_api_tokens",
         "responses": {
           "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "properties": {
+                    "api_tokens": {
+                      "items": {
+                        "$ref": "#/components/schemas/ApiToken"
+                      },
+                      "type": "array"
+                    }
+                  },
+                  "required": [
+                    "api_tokens"
+                  ],
+                  "type": "object"
+                }
+              }
+            },
             "description": "Successful Response"
           }
         },