Improve the usability of HTTP API documentation

[KrishnaIyer]

Summary

Improve the usability of HTTP API documentation

Why do we need this ?

Based on feedback on talking to customers, there are concrete updates that we can do.

What is already there? What do you see now?

Our first version of the API docs: https://www.thethingsindustries.com/docs/api/reference/http/

What is missing? What do you want to see?

Improved usability

How do you propose to document this?

• Split the APIs into different files. openapi.html should accept a service tag as a parameter and only create the relevant services.
• Improve the request sections by indicating which params are path, query and body.
• For body params,
  • Link directly to the message instead of the unfolded JSON schema. When users click and go to the message, add an option for users to select fields in a message to generate a JSON.
  • For body params with field masks, implement the above directly in the request location. Allow users to choose the fieldmasks and then generate a JSON for that fieldmask.
• (Optional): Allow users to try requests using input fields
• (Optional): Add a global "server" component that can be set by the user and is applied across the entire documentation.

Can you do this yourself and submit a Pull Request?

Yes