mgr/dashboard: fix nvmeof api documentation

From Aviv:
POST /api/nvmeof/hosts - the description of the command it wrong IMO. It is not about creating a host. It is about allowing a host X to access subsystem Y.
GET /api/nvmeof/hosts/{subsystem_nqn} - also the description is not accurate. The command lists all hosts that are allowed to access this subsystem.
DELETE /api/nvmeof/hosts/{subsystem_nqn}/{host_nqn} - again the description should be changed as above.
POST /api/nvmeof/namespace - bad formatting of the description
GET /api/nvmeof/subsystem - the description is wrong, should say - "List all NVMeoF subsystems". And it shouldn't get any param.
POST /api/nvmeof/subsystem - few issues here. The serial_number, and max_namespaces are optional (we need to mention that). Also it is missing the --enable-ha argument that is also optional.
Some commands are missing: log_level, connection.i

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

Author: nizamial09

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

@@ -17,46 +17,47 @@
     @APIDoc('NVMe-oF Namespace Management API', 'NVMe-oF')
     class NvmeofNamespace(RESTController):
         @ReadPermission
+        @EndpointDoc('List all NVMeoF namespaces',
+                     parameters={
+                         'subsystem_nqn': (str, 'NVMeoF subsystem NQN')
+                     })
         def list(self, subsystem_nqn: str):
-            """
-            List all NVMeoF namespaces
-            """
             response = MessageToJson(NVMeoFClient().list_namespaces(subsystem_nqn))
             return json.loads(response)
 
         @CreatePermission
+        @EndpointDoc('Create a new NVMeoF namespace',
+                     parameters={
+                         'rbd_pool': (str, 'RBD pool name'),
+                         'rbd_image': (str, 'RBD image name'),
+                         'subsystem_nqn': (str, 'NVMeoF subsystem NQN'),
+                         'create_image': (bool, 'Create RBD image'),
+                         'image_size': (int, 'RBD image size'),
+                         'block_size': (int, 'NVMeoF namespace block size')
+                     })
         def create(self, rbd_pool: str, rbd_image: str, subsystem_nqn: str,
                    create_image: Optional[bool] = True, image_size: Optional[int] = 1024,
                    block_size: int = 512):
-            """
-            Create a new NVMeoF namespace
-            :param rbd_pool: RBD pool name
-            :param rbd_image: RBD image name
-            :param subsystem_nqn: NVMeoF subsystem NQN
-            :param create_image: Create RBD image
-            :param image_size: RBD image size
-            :param block_size: NVMeoF namespace block size
-            """
             response = NVMeoFClient().create_namespace(rbd_pool, rbd_image,
                                                        subsystem_nqn, block_size,
                                                        create_image, image_size)
             return json.loads(MessageToJson(response))
 
         @Endpoint('DELETE', path='{subsystem_nqn}')
+        @EndpointDoc('Delete an existing NVMeoF namespace',
+                     parameters={
+                         'subsystem_nqn': (str, 'NVMeoF subsystem NQN')
+                     })
         @DeletePermission
         def delete(self, subsystem_nqn: str):
-            """
-            Delete an existing NVMeoF namespace
-            :param subsystem_nqn: NVMeoF subsystem NQN
-            """
             response = NVMeoFClient().delete_namespace(subsystem_nqn)
             return json.loads(MessageToJson(response))
 
     @APIRouter('/nvmeof/subsystem', Scope.NVME_OF)
     @APIDoc('NVMe-oF Subsystem Management API', 'NVMe-oF')
     class NvmeofSubsystem(RESTController):
         @ReadPermission
-        @EndpointDoc("List all NVMeoF gateways",
+        @EndpointDoc("List all NVMeoF subsystems",
                      parameters={
                          'subsystem_nqn': (str, 'NVMeoF subsystem NQN'),
                      })
@@ -68,92 +69,90 @@ def list(self, subsystem_nqn: Optional[str] = None):
             return json.loads(response)
 
         @CreatePermission
-        def create(self, subsystem_nqn: str, serial_number: Optional[str] = None,
-                   max_namespaces: Optional[int] = 256):
-            """
-            Create a new NVMeoF subsystem
-
-            :param subsystem_nqn: NVMeoF subsystem NQN
-            :param serial_number: NVMeoF subsystem serial number
-            :param max_namespaces: NVMeoF subsystem maximum namespaces
-            """
-            response = NVMeoFClient().create_subsystem(subsystem_nqn, serial_number, max_namespaces)
+        @EndpointDoc('Create a new NVMeoF subsystem',
+                     parameters={
+                         'subsystem_nqn': (str, 'NVMeoF subsystem NQN'),
+                         'serial_number': (str, 'NVMeoF subsystem serial number'),
+                         'max_namespaces': (int, 'Maximum number of namespaces')
+                     })
+        def create(self, subsystem_nqn: str):
+            response = NVMeoFClient().create_subsystem(subsystem_nqn)
             return json.loads(MessageToJson(response))
 
         @DeletePermission
         @Endpoint('DELETE', path='{subsystem_nqn}')
+        @EndpointDoc('Delete an existing NVMeoF subsystem',
+                     parameters={
+                         'subsystem_nqn': (str, 'NVMeoF subsystem NQN'),
+                         'force': (bool, 'Force delete')
+                     })
         def delete(self, subsystem_nqn: str, force: Optional[bool] = False):
-            """
-            Delete an existing NVMeoF subsystem
-            :param subsystem_nqn: NVMeoF subsystem NQN
-            :param force: Force delete
-            """
             response = NVMeoFClient().delete_subsystem(subsystem_nqn, force)
             return json.loads(MessageToJson(response))
 
     @APIRouter('/nvmeof/hosts', Scope.NVME_OF)
     @APIDoc('NVMe-oF Host Management API', 'NVMe-oF')
     class NvmeofHost(RESTController):
         @ReadPermission
+        @EndpointDoc('List all allowed hosts for an NVMeoF subsystem',
+                     parameters={
+                         'subsystem_nqn': (str, 'NVMeoF subsystem NQN')
+                     })
         def list(self, subsystem_nqn: str):
-            """
-            List all NVMeoF hosts
-            :param subsystem_nqn: NVMeoF subsystem NQN
-            """
             response = MessageToJson(NVMeoFClient().list_hosts(subsystem_nqn))
             return json.loads(response)
 
         @CreatePermission
+        @EndpointDoc('Allow hosts to access an NVMeoF subsystem',
+                     parameters={
+                         'subsystem_nqn': (str, 'NVMeoF subsystem NQN'),
+                         'host_nqn': (str, 'NVMeoF host NQN')
+                     })
         def create(self, subsystem_nqn: str, host_nqn: str):
-            """
-            Create a new NVMeoF host
-            :param subsystem_nqn: NVMeoF subsystem NQN
-            :param host_nqn: NVMeoF host NQN
-            """
             response = NVMeoFClient().add_host(subsystem_nqn, host_nqn)
             return json.loads(MessageToJson(response))
 
         @DeletePermission
+        @EndpointDoc('Disallow hosts from accessing an NVMeoF subsystem',
+                     parameters={
+                         'subsystem_nqn': (str, 'NVMeoF subsystem NQN'),
+                         'host_nqn': (str, 'NVMeoF host NQN')
+                     })
         def delete(self, subsystem_nqn: str, host_nqn: str):
-            """
-            Delete an existing NVMeoF host
-            :param subsystem_nqn: NVMeoF subsystem NQN
-            :param host_nqn: NVMeoF host NQN
-            """
             response = NVMeoFClient().remove_host(subsystem_nqn, host_nqn)
             return json.loads(MessageToJson(response))
 
     @APIRouter('/nvmeof/listener', Scope.NVME_OF)
     @APIDoc('NVMe-oF Listener Management API', 'NVMe-oF')
     class NvmeofListener(RESTController):
         @ReadPermission
+        @EndpointDoc('List all NVMeoF listeners',
+                     parameters={
+                         'subsystem_nqn': (str, 'NVMeoF subsystem NQN')
+                     })
         def list(self, subsystem_nqn: str):
-            """
-            List all NVMeoF listeners
-            :param nqn: NVMeoF subsystem NQN
-            """
             response = MessageToJson(NVMeoFClient().list_listeners(subsystem_nqn))
             return json.loads(response)
 
         @CreatePermission
+        @EndpointDoc('Create a new NVMeoF listener',
+                     parameters={
+                         'nqn': (str, 'NVMeoF subsystem NQN'),
+                         'gateway': (str, 'NVMeoF gateway'),
+                         'traddr': (str, 'NVMeoF transport address')
+                     })
         def create(self, nqn: str, gateway: str, traddr: Optional[str] = None):
-            """
-            Create a new NVMeoF listener
-            :param nqn: NVMeoF subsystem NQN
-            :param gateway: NVMeoF gateway
-            :param traddr: NVMeoF transport address
-            """
             response = NVMeoFClient().create_listener(nqn, gateway, traddr)
             return json.loads(MessageToJson(response))
 
         @DeletePermission
+        @EndpointDoc('Delete an existing NVMeoF listener',
+                     parameters={
+                         'nqn': (str, 'NVMeoF subsystem NQN'),
+                         'gateway': (str, 'NVMeoF gateway'),
+                         'traddr': (str, 'NVMeoF transport address')
+                     })
         def delete(self, nqn: str, gateway: str, traddr: Optional[str] = None):
-            """
-            Delete an existing NVMeoF listener
-            :param nqn: NVMeoF subsystem NQN
-            :param gateway: NVMeoF gateway
-            :param traddr: NVMeoF transport address
-            """
             response = NVMeoFClient().delete_listener(nqn, gateway, traddr)
             return json.loads(MessageToJson(response))
 
@@ -162,9 +161,7 @@ def delete(self, nqn: str, gateway: str, traddr: Optional[str] = None):
     class NvmeofGateway(RESTController):
         @ReadPermission
         @Endpoint()
+        @EndpointDoc('List all NVMeoF gateways')
         def info(self):
-            """
-            Get NVMeoF gateway information
-            """
             response = MessageToJson(NVMeoFClient().gateway_info())
             return json.loads(response)