openwisp-controller icon indicating copy to clipboard operation
openwisp-controller copied to clipboard

[ux/docs] Improve usability & docs of REST API endpoint to execute commands

Open nemesifier opened this issue 7 months ago • 0 comments

Using the REST API to execute custom commands is currently not straightforward due to several issues:

  • The “Send Commands” documentation page for OpenWISP 24.11 does not mention the possibility of performing this operation via the REST API. It would be useful to include this, along with a link to the relevant REST API section.
  • The REST API section on executing shell commands does not describe the required payload structure for sending custom commands.
  • Neither the browsable API nor the OpenAPI documentation provides guidance on what should be entered in the input field.

Because the endpoint relies on dynamic logic, it may not be easy to implement a serializer that guides the user through the API docs or browsable API interface. If this can be achieved without adding too much complexity, it would be ideal. Alternatively, we can improve the documentation and ensure the same explanation appears in the browsable API.

Another issue is that the API documentation does not show any information about the expected input parameters (see the screenshot below). We should consider tweaking the serializer to ensure the input format is clearly explained.

Image

nemesifier avatar May 16 '25 20:05 nemesifier