Another source for getting started with MQTT 2.x is MQTT 2.5 Event Bus. The first part is generic MQTT stuff which might prove useful.
I and others recommend managing all Things through PaperUI. You can’t generate syntax errors and all the options are presented there in the form including what they mean and sometimes examples of what to put in the fields. At a minimum I recommend at least creating the first one that way and then looking at the JSON and examples on the forum to convert it to a .things file. If you have a lot of similar MQTT Things to create and want to use PaperUI/Karaf Console/REST API to manage them I recommend:
- Creating the first one through PaperUI
- Query for that newly created one in the REST API
- Copy the JSON to a text editor
- Modify the JSON with the values for another Thing
- Submit the modified JSON to the REST API
NOTE: In OH 3 the UI handles this much better. You can copy and paste everything right there in the MainUI.