I prefer a hybrid approach. A document explaining some common things to do and generally the idea behind why the API is structured that way (shows me you actually thought about it, and makes it more logical to find different parts of it without necessarily looking it up), and then an API spec showing all the parameters.
I’ve actually used this to my advantage. I bought some cheap speaker/light combos which basically made the lights dance to the music. The only power connector was a wire that comes straight out of the device and into an outlet. But it did have a USB port for loading music from a USB stick. So naturally I plugged one side of a USB A into the port and the other side into a power bank and it just straight up worked.