[docs/ui] Improve docs of send commands API endpoint #1047

Closes #1047

Author: pandafy

docs/user/rest-api.rst

@@ -347,13 +347,110 @@ List Commands of a Device
 
     GET /api/v1/controller/device/{device_id}/command/
 
+.. _controller_execute_command_api:
+
 Execute a Command on a Device
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: text
 
     POST /api/v1/controller/device/{device_id}/command/
 
+This endpoint allows you to execute various types of commands on a device.
+
+**Request Parameters**
+
+============== ========================================================
+Parameter      Description
+============== ========================================================
+``type``       The type of command to execute (**required**)
+``input``      Input data for the command (format varies by type)
+               (**required**)
+``connection`` UUID of specific device connection to use (**optional**)
+============== ========================================================
+
+The ``input`` field requires data in a specific format that depends on the
+command type being executed.
+
+.. note::
+
+    The following examples show payloads for the default commands shipped
+    with OpenWISP. The available commands on a device depend on your
+    configuration of :ref:`OPENWISP_CONTROLLER_USER_COMMANDS
+    <openwisp_controller_user_commands>` and
+    :ref:`OPENWISP_CONTROLLER_ORGANIZATION_ENABLED_COMMANDS` settings. For
+    detailed information about command execution, including how to add
+    command types, and restrict available commands per organization, see
+    :doc:`shell-commands`.
+
+**Available Command Types**
+
+1. **Custom Command** (``custom``)
+
+   Execute a custom command on the device.
+
+   **Input format:** ``{"command": "shell_command"}``
+
+   **Example payload:**
+
+   .. code-block:: json
+
+       {
+           "type": "custom",
+           "input": {
+               "command": "iwinfo"
+           }
+       }
+
+2. **Reboot** (``reboot``)
+
+   Reboot the device.
+
+   **Input format:** ``null`` (no input required)
+
+   **Example payload:**
+
+   .. code-block:: json
+
+       {
+           "type": "reboot",
+           "input": null
+       }
+
+3. **Change Password** (``change_password``)
+
+   Change the device's root password.
+
+   **Input format:** ``{"password": "new_pass", "confirm_password":
+   "new_pass"}``
+
+   **Example payload:**
+
+   .. code-block:: json
+
+       {
+           "type": "change_password",
+           "input": {
+               "password": "newpassword123",
+               "confirm_password": "newpassword123"
+           }
+       }
+
+**Example Request:**
+
+.. code-block:: shell
+
+    curl -X POST \
+        http://127.0.0.1:8000/api/v1/controller/device/76b7d9cc-4ffd-4a43-b1b0-8f8befd1a7c0/command/ \
+        -H 'authorization: Bearer yoursecretauthtoken' \
+        -H 'content-type: application/json' \
+        -d '{
+                "type": "custom",
+                "input": {
+                    "command": "uptime"
+                }
+            }'
+
 Get Command Details
 ~~~~~~~~~~~~~~~~~~~
 

docs/user/shell-commands.rst

@@ -36,6 +36,11 @@ used often in your network regardless of your users' knowledge of Linux
 shell commands, you can add new commands by following instructions in the
 :ref:`defining_new_menu_options` section below.
 
+.. note::
+
+    You can also use the `REST API <controller_execute_command_api>`_ to
+    execute commands on a device.
+
 .. note::
 
     If you're an advanced user and want to learn how to register commands

openwisp_controller/connection/api/serializers.py

@@ -1,3 +1,5 @@
+from django.utils.safestring import mark_safe
+from django.utils.translation import gettext_lazy as _
 from rest_framework import serializers
 from swapper import load_model
 
@@ -20,7 +22,18 @@ def validate(self, data):
 
 
 class CommandSerializer(ValidatedDeviceFieldSerializer):
-    input = serializers.JSONField(allow_null=True)
+    input = serializers.JSONField(
+        allow_null=True,
+        help_text=mark_safe(
+            _(
+                "JSON object containing the command input data. "
+                "The structure of this object depends on the command type. "
+                'Refer to the <a href="https://openwisp.io/docs/dev/controller/'
+                'user/rest-api.html#execute-a-command-on-a-device" target="_blank">'
+                "OpenWISP documentation</a> for details."
+            )
+        ),
+    )
     device = serializers.PrimaryKeyRelatedField(
         read_only=True, pk_field=serializers.UUIDField(format="hex_verbose")
     )

openwisp_controller/connection/api/views.py

@@ -1,4 +1,7 @@
 from django.core.exceptions import ValidationError
+from django.utils.translation import gettext_lazy as _
+from drf_yasg import openapi
+from drf_yasg.utils import swagger_auto_schema
 from rest_framework import pagination
 from rest_framework.exceptions import NotFound
 from rest_framework.generics import (
@@ -73,6 +76,22 @@ def create(self, request, *args, **kwargs):
         self.assert_parent_exists()
         return super().create(request, *args, **kwargs)
 
+    @swagger_auto_schema(
+        operation_description=_("Execute a command on a device"),
+        operation_summary=_("Execute device command"),
+        request_body=CommandSerializer,
+        responses={
+            201: openapi.Response(
+                description=_("Command created successfully"),
+                schema=CommandSerializer,
+            ),
+            400: openapi.Response(description=_("Invalid request data")),
+            404: openapi.Response(description=_("Device not found")),
+        },
+    )
+    def post(self, request, *args, **kwargs):
+        return super().post(request, *args, **kwargs)
+
 
 class CommandDetailsView(BaseCommandView, RetrieveAPIView):
     def get_object(self):