Merge pull request #58951 from rhcs-dashboard/ceph-users-doc-fix

mgr/dashboard: fix ceph-users api

Reviewed-by: Zac Dover <zac.dover@proton.me>

2 files changed, 63 insertions, 25 deletions

diff --git a/src/pybind/mgr/dashboard/controllers/ceph_users.py b/src/pybind/mgr/dashboard/controllers/ceph_users.py
index 022f8f36c42..8bc47133bc7 100644
--- a/src/pybind/mgr/dashboard/controllers/ceph_users.py
+++ b/src/pybind/mgr/dashboard/controllers/ceph_users.py
@@ -6,7 +6,7 @@ from ..exceptions import DashboardException
 from ..security import Scope
 from ..services.ceph_service import CephService, SendCommandError
 from . import APIDoc, APIRouter, CRUDCollectionMethod, CRUDEndpoint, \
-    EndpointDoc, RESTController, SecretStr
+    EndpointDoc, Param, RESTController, SecretStr
 from ._crud import ArrayHorizontalContainer, CRUDMeta, Form, FormField, \
     FormTaskInfo, Icon, MethodType, SelectionType, TableAction, Validator, \
     VerticalContainer
@@ -40,7 +40,7 @@ class CephUserEndpoints:
     @staticmethod
     def user_list(_):
         """
-        Get list of ceph users and its respective data
+        Get list of ceph users and its associated data
         """
         return CephUserEndpoints._run_auth_command('auth ls')["auth_dump"]
 
@@ -48,9 +48,7 @@ class CephUserEndpoints:
     def user_create(_, user_entity: str = '', capabilities: Optional[List[Cap]] = None,
                     import_data: str = ''):
         """
-        Add a ceph user with its defined capabilities.
-        :param user_entity: Entity to change
-        :param capabilities: List of capabilities to add to user_entity
+        Add a Ceph user, with its defined capabilities.
         """
         # Caps are represented as a vector in mon auth add commands.
         # Look at AuthMonitor.cc::valid_caps for reference.
@@ -75,7 +73,6 @@ class CephUserEndpoints:
     def user_delete(_, user_entity: str):
         """
         Delete a ceph user and it's defined capabilities.
-        :param user_entity: Entity to delete
         """
         logger.debug("Sending command 'auth del' of entity '%s'", user_entity)
         CephUserEndpoints._run_auth_command('auth del', entity=user_entity)
@@ -94,8 +91,6 @@ class CephUserEndpoints:
         """
         Change the ceph user capabilities.
         Setting new capabilities will overwrite current ones.
-        :param user_entity: Entity to change
-        :param capabilities: List of updated capabilities to user_entity
         """
         caps = []
         for cap in capabilities:
@@ -188,19 +183,36 @@ edit_form = Form(path='/cluster/user/edit',
     resource='user',
     get_all=CRUDCollectionMethod(
         func=CephUserEndpoints.user_list,
-        doc=EndpointDoc("Get Ceph Users")
+        doc=EndpointDoc("Get list of ceph users")
     ),
     create=CRUDCollectionMethod(
         func=CephUserEndpoints.user_create,
-        doc=EndpointDoc("Create Ceph User")
+        doc=EndpointDoc("Create Ceph User",
+                        parameters={
+                            "user_entity": Param(str, "Entity to add"),
+                            'capabilities': Param([{
+                                "entity": (str, "Entity to add"),
+                                "cap": (str, "Capability to add; eg. allow *")
+                            }], 'List of capabilities to add to user_entity')
+                        })
     ),
     edit=CRUDCollectionMethod(
         func=CephUserEndpoints.user_edit,
-        doc=EndpointDoc("Edit Ceph User")
+        doc=EndpointDoc("Edit Ceph User Capabilities",
+                        parameters={
+                            "user_entity": Param(str, "Entity to edit"),
+                            'capabilities': Param([{
+                                "entity": (str, "Entity to edit"),
+                                "cap": (str, "Capability to edit; eg. allow *")
+                            }], 'List of updated capabilities to user_entity')
+                        })
     ),
     delete=CRUDCollectionMethod(
         func=CephUserEndpoints.user_delete,
-        doc=EndpointDoc("Delete Ceph User")
+        doc=EndpointDoc("Delete Ceph User",
+                        parameters={
+                            "user_entity": Param(str, "Entity to delete")
+                        })
     ),
     extra_endpoints=[
         ('export', CRUDCollectionMethod(
diff --git a/src/pybind/mgr/dashboard/openapi.yaml b/src/pybind/mgr/dashboard/openapi.yaml
index 798689d0e89..b5a34304ada 100644
--- a/src/pybind/mgr/dashboard/openapi.yaml
+++ b/src/pybind/mgr/dashboard/openapi.yaml
@@ -3740,7 +3740,7 @@ paths:
       - Upgrade
   /api/cluster/user:
     get:
-      description: "\n        Get list of ceph users and its respective data\n   \
+      description: "\n        Get list of ceph users and its associated data\n   \
         \     "
       parameters: []
       responses:
@@ -3760,13 +3760,12 @@ paths:
             trace.
       security:
       - jwt: []
-      summary: Get Ceph Users
+      summary: Get list of ceph users
       tags:
       - Cluster
     post:
-      description: "\n        Add a ceph user with its defined capabilities.\n   \
-        \     :param user_entity: Entity to change\n        :param capabilities: List\
-        \ of capabilities to add to user_entity\n        "
+      description: "\n        Add a Ceph user, with its defined capabilities.\n  \
+        \      "
       parameters: []
       requestBody:
         content:
@@ -3774,12 +3773,26 @@ paths:
             schema:
               properties:
                 capabilities:
-                  type: string
+                  description: List of capabilities to add to user_entity
+                  items:
+                    properties:
+                      cap:
+                        description: Capability to add; eg. allow *
+                        type: string
+                      entity:
+                        description: Entity to add
+                        type: string
+                    required:
+                    - entity
+                    - cap
+                    type: object
+                  type: array
                 import_data:
                   default: ''
                   type: string
                 user_entity:
                   default: ''
+                  description: Entity to add
                   type: string
               type: object
       responses:
@@ -3809,9 +3822,7 @@ paths:
       - Cluster
     put:
       description: "\n        Change the ceph user capabilities.\n        Setting\
-        \ new capabilities will overwrite current ones.\n        :param user_entity:\
-        \ Entity to change\n        :param capabilities: List of updated capabilities\
-        \ to user_entity\n        "
+        \ new capabilities will overwrite current ones.\n        "
       parameters: []
       requestBody:
         content:
@@ -3819,9 +3830,23 @@ paths:
             schema:
               properties:
                 capabilities:
-                  type: string
+                  description: List of updated capabilities to user_entity
+                  items:
+                    properties:
+                      cap:
+                        description: Capability to edit; eg. allow *
+                        type: string
+                      entity:
+                        description: Entity to edit
+                        type: string
+                    required:
+                    - entity
+                    - cap
+                    type: object
+                  type: array
                 user_entity:
                   default: ''
+                  description: Entity to edit
                   type: string
               type: object
       responses:
@@ -3846,7 +3871,7 @@ paths:
             trace.
       security:
       - jwt: []
-      summary: Edit Ceph User
+      summary: Edit Ceph User Capabilities
       tags:
       - Cluster
   /api/cluster/user/export:
@@ -3890,9 +3915,10 @@ paths:
   /api/cluster/user/{user_entity}:
     delete:
       description: "\n        Delete a ceph user and it's defined capabilities.\n\
-        \        :param user_entity: Entity to delete\n        "
+        \        "
       parameters:
-      - in: path
+      - description: Entity to delete
+        in: path
         name: user_entity
         required: true
         schema: