Fixed a bunch of doc issues, updated /api/printer/command to have more meaningful error messages

docs/api/printer.rst

@@ -758,29 +758,57 @@ Retrieve the current SD state
 .. _sec-api-printer-arbcommand:
 
 Send an arbitrary command to the printer
-=============================
+========================================
 
 .. http:post:: /api/printer/command
 
-   Sends any command to the printer via serial inerface. Should be used with some care as some commands can stop a running print job. 
+   Sends any command to the printer via the serial interface. Should be used with some care as some commands can interfere with
+   or even stop a running print job.
+
+   Expects a :ref:`Arbitrary Command Request <sec-api-printer-datamodel-arbcommand>` as the request's body.
 
    If successful returns a :http:statuscode:`204` and an empty body.
 
-   **Example Request**
+   **Example for sending a single command**
 
    .. sourcecode:: http
+
       POST /api/printer/command HTTP/1.1
       Host: example.com
       Content-Type: application/json
       X-Api-Key: abcdef...
 
       {
-        "command": "M27"
+        "command": "M106"
       }
 
+   .. sourcecode:: http
+
+      HTTP/1.1 204 No Content
+
+   **Example for sending multiple commands**
+
+   .. sourcecode:: http
+
+      POST /api/printer/command HTTP/1.1
+      Host: example.com
+      Content-Type: application/json
+      X-Api-Key: abcdef...
+
+      {
+        "commands": [
+          "M18",
+          "M106 S0"
+        ]
+      }
+
+   .. sourcecode:: http
+
+      HTTP/1.1 204 No Content
    
-   :json string command: The command to issue.
-   :statuscode 204:      No error
+   :json string command:  Single command to send to the printer, mutually exclusive with ``commands``.
+   :json string commands: List of commands to send to the printer, mutually exclusive with ``command``.
+   :statuscode 204:       No error
 
 .. _sec-api-printer-datamodel:
 
@@ -857,3 +885,25 @@ SD State
      - 1
      - Boolean
      - Whether the SD card has been initialized (``true``) or not (``false``).
+
+.. _sec-api-printer-datamodel-arbcommand:
+
+Arbitrary Command Request
+-------------------------
+
+.. list-table::
+   :widths: 15 5 10 30
+   :header-rows: 1
+
+   * - Name
+     - Multiplicity
+     - Type
+     - Description
+   * - ``command``
+     - 0..1
+     - String
+     - Single command to send to the printer, mutually exclusive with ``commands``.
+   * - ``commands``
+     - 0..*
+     - Array of String
+     - Multiple commands to send to the printer (in the given order), mutually exclusive with ``command``.

src/octoprint/server/api/printer.py

@@ -300,7 +300,6 @@ def printerSdState():
 @api.route("/printer/command", methods=["POST"])
 @restricted_access
 def printerCommand():
-	# TODO: document me
 	if not printer.isOperational():
 		return make_response("Printer is not operational", 409)
 
@@ -309,15 +308,17 @@ def printerCommand():
 
 	data = request.json
 
-	parameters = {}
-	if "parameters" in data.keys():
-		parameters = data["parameters"]
+	parameters = dict()
+	if "parameters" in data.keys(): parameters = data["parameters"]
 
-	commands = []
-	if "command" in data.keys():
+	if "command" in data and "commands" in data:
+		return make_response("'command' and 'commands' are mutually exclusive", 400)
+	elif "command" in data:
 		commands = [data["command"]]
-	elif "commands" in data.keys():
+	elif "commands" in data and isinstance(data["commands"], (list, tuple)):
 		commands = data["commands"]
+	else:
+		return make_response("Need either single 'command' or list of 'commands'", 400)
 
 	commandsToSend = []
 	for command in commands: