Tweak the schema to use summary instead of description and add tags

Author: sandhose

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 {

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 =

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);

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());

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"
+    }
   ]
 }