mgr/dashboard: fix ceph-users api doc

Fixes: https://tracker.ceph.com/issues/67224
Signed-off-by: Nizamudeen A <[email protected]>

Author: nizamial09

src/pybind/mgr/dashboard/controllers/ceph_users.py

@@ -6,7 +6,7 @@
 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,17 +40,15 @@ def _run_auth_command(command: str, *args, **kwargs):
     @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"]
 
     @staticmethod
     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 @@ def user_create(_, user_entity: str = '', capabilities: Optional[List[Cap]] = No
     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 @@ def user_edit(_, user_entity: str = '', capabilities: List[Cap] = None):
         """
         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 @@ def model(user_entity: str):
     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(

src/pybind/mgr/dashboard/openapi.yaml

@@ -3691,7 +3691,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:
@@ -3711,26 +3711,39 @@ 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:
           application/json:
             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:
@@ -3760,19 +3773,31 @@ 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:
           application/json:
             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:
@@ -3797,7 +3822,7 @@ paths:
             trace.
       security:
       - jwt: []
-      summary: Edit Ceph User
+      summary: Edit Ceph User Capabilities
       tags:
       - Cluster
   /api/cluster/user/export:
@@ -3841,9 +3866,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: