Consider improving menu structure for the API docs

[jancurn]

The current API ref menu structure is not ideal. Apiary forces us to use artificial categories like "Run collection", which is super confusing. It's hard to find endpoints in the menu.

In an ideal world, we'd have a simple structure with categories corresponding to areas of product, and then list of endpoints under each category. BTW this is how Stripe has it https://stripe.com/docs/api/

See this conversation: https://apifier.slack.com/archives/CQ96RHG2U/p1580899496004200

[mtrunkat]

I'd first consider migrating our API docs to Swagger as:

• It will be much easier to maintain (allows to split it to multiple files and have object schemas in separate files)
• We will be able to use if pragmatically in tests as it's either YAML or JSON instead of a markdown

And then consider using some open source docs generator as we will be able to modify the theme:

• https://github.com/sourcey/spectacle
• https://github.com/slatedocs/slate (both inspired by Stripe)

[jancurn]

Good point. Using some of these tools could let us integrate the API docs better into our docs structure, use the same menu etc...

[mtrunkat]

Adding 55 points. We should eventually split this into multiple tasks:

• migration of docs to swagger
• cleanup of swagger
• implementation of a renderer
• update of all links to API docs
• ...

[mtrunkat]

Moved to Product Board: https://apify.productboard.com/feature-board/423133-all-development-features/features/11215370/detail