Include example HTTP request payload and response for each API endpoint in the API documentation

There are some curl examples at https://api.stackstorm.com/

But we should update API docs code generation code to include example request payload and example response for each API endpoint.

API docs without examples are nice, but not all that useful. With examples in place it's much faster and easier to get started (it's the same with regular code docs - just API reference documentation is not that useful, you need actual code samples, etc.).

To make the whole thing maintainable, actual payload examples should be tested. This means we need to write sample payload fixture files which we then use in st2api tests. Those example files are then also used inside the API docs.

Here is an example of docs I worked on in the past which includes examples which are tested (we used the same example payloads in our test suite) - https://developer.rackspace.com/docs/rackspace-monitoring/v1/api-reference/entities-operations/#create-an-entity.

This means no manual one off examples or similar. Examples which are not automatically tested are worse then no examples (they create maintenance burden and it's easy for them to get out of date and become wrong).

In addition to the sample request payload and response, we should also include example cURL line which uses data from the sample request fixture.

Once we also have Python client code automatically generated from the specs we should also include st2client examples (probably not worth spending the effort now in writing the code which would generate examples for the current st2client code).

Related repos:

• https://github.com/StackStorm/st2apidocs
• https://github.com/StackStorm/st2apidocgen

Start by reviewing the related st2apidocs and st2apidocgen repositories, then trace the API documentation generation code and the st2api tests. Define how sample request and response fixture files are consumed by tests and documentation generation. Done means every API endpoint has tested request, response, and cURL examples, with no manually maintained one-off examples.