From cdecac735ea82424dda7f5e6637bbbe5708fe403 Mon Sep 17 00:00:00 2001
From: Quentin Gliech <quenting@element.io>
Date: Fri, 26 Jul 2024 17:19:15 +0200
Subject: [PATCH] Tweak the schema to use summary instead of description and
 add tags

---
 crates/handlers/src/admin/mod.rs              |  7 ++++++-
 .../src/admin/v1/users/by_username.rs         |  3 ++-
 crates/handlers/src/admin/v1/users/get.rs     |  3 ++-
 crates/handlers/src/admin/v1/users/list.rs    |  3 ++-
 docs/api/spec.json                            | 21 ++++++++++++++++---
 5 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/crates/handlers/src/admin/mod.rs b/crates/handlers/src/admin/mod.rs
index 618f8333..3019977f 100644
--- a/crates/handlers/src/admin/mod.rs
+++ b/crates/handlers/src/admin/mod.rs
@@ -14,7 +14,7 @@
 
 use aide::{
     axum::ApiRouter,
-    openapi::{OAuth2Flow, OAuth2Flows, OpenApi, SecurityScheme, Server},
+    openapi::{OAuth2Flow, OAuth2Flows, OpenApi, SecurityScheme, Server, Tag},
 };
 use axum::{
     extract::{FromRef, FromRequestParts, State},
@@ -53,6 +53,11 @@ where
         .nest("/api/admin/v1", self::v1::router())
         .finish_api_with(&mut api, |t| {
             t.title("Matrix Authentication Service admin API")
+                .tag(Tag {
+                    name: "user".to_owned(),
+                    description: Some("Manage users".to_owned()),
+                    ..Tag::default()
+                })
                 .security_scheme(
                     "oauth2",
                     SecurityScheme::OAuth2 {
diff --git a/crates/handlers/src/admin/v1/users/by_username.rs b/crates/handlers/src/admin/v1/users/by_username.rs
index ec177802..55803228 100644
--- a/crates/handlers/src/admin/v1/users/by_username.rs
+++ b/crates/handlers/src/admin/v1/users/by_username.rs
@@ -58,7 +58,8 @@ pub struct UsernamePathParam {
 
 pub fn doc(operation: TransformOperation) -> TransformOperation {
     operation
-        .description("Get a user by its username (localpart)")
+        .summary("Get a user by its username (localpart)")
+        .tag("user")
         .response_with::<200, Json<SingleResponse<User>>, _>(|t| {
             let [sample, ..] = User::samples();
             let response =
diff --git a/crates/handlers/src/admin/v1/users/get.rs b/crates/handlers/src/admin/v1/users/get.rs
index 4b6fdcee..8e848359 100644
--- a/crates/handlers/src/admin/v1/users/get.rs
+++ b/crates/handlers/src/admin/v1/users/get.rs
@@ -52,7 +52,8 @@ impl IntoResponse for RouteError {
 
 pub fn doc(operation: TransformOperation) -> TransformOperation {
     operation
-        .description("Get a user")
+        .summary("Get a user")
+        .tag("user")
         .response_with::<200, Json<SingleResponse<User>>, _>(|t| {
             let [sample, ..] = User::samples();
             let response = SingleResponse::new_canonical(sample);
diff --git a/crates/handlers/src/admin/v1/users/list.rs b/crates/handlers/src/admin/v1/users/list.rs
index b3aebf12..d5dc46df 100644
--- a/crates/handlers/src/admin/v1/users/list.rs
+++ b/crates/handlers/src/admin/v1/users/list.rs
@@ -100,7 +100,8 @@ impl IntoResponse for RouteError {
 
 pub fn doc(operation: TransformOperation) -> TransformOperation {
     operation
-        .description("List users")
+        .summary("List users")
+        .tag("user")
         .response_with::<200, Json<PaginatedResponse<User>>, _>(|t| {
             let users = User::samples();
             let pagination = mas_storage::Pagination::first(users.len());
diff --git a/docs/api/spec.json b/docs/api/spec.json
index c099ecf5..c94599e3 100644
--- a/docs/api/spec.json
+++ b/docs/api/spec.json
@@ -18,7 +18,10 @@
   "paths": {
     "/api/admin/v1/users": {
       "get": {
-        "description": "List users",
+        "tags": [
+          "user"
+        ],
+        "summary": "List users",
         "parameters": [
           {
             "in": "query",
@@ -171,7 +174,10 @@
     },
     "/api/admin/v1/users/{id}": {
       "get": {
-        "description": "Get a user",
+        "tags": [
+          "user"
+        ],
+        "summary": "Get a user",
         "parameters": [
           {
             "in": "path",
@@ -238,7 +244,10 @@
     },
     "/api/admin/v1/users/by-username/{username}": {
       "get": {
-        "description": "Get a user by its username (localpart)",
+        "tags": [
+          "user"
+        ],
+        "summary": "Get a user by its username (localpart)",
         "parameters": [
           {
             "in": "path",
@@ -631,5 +640,11 @@
         "urn:mas:admin"
       ]
     }
+  ],
+  "tags": [
+    {
+      "name": "user",
+      "description": "Manage users"
+    }
   ]
 }