API-5: documentation and specs

[wvengen]

Part five of #429 in chunks, continued from #573:

• API documentation
• Specs
• Fix for Doorkeeper 5 compatibility (came up working on the specs)

To render the swagger file, see here.

[paroga]

i'd like to have the changes on the existing test in it's own commit, add the tests in the same commit as the controllers. why didn't you add the required column not in the first commit?

[wvengen]

I could add the specs in separate commits if you like. I agree that would have been nicer. When writing, it felt like an additional feature (docs, then specs based on the docs), but you're right. I'll refactor it and create a separate PR / add it to the existing PRs.

I only discovered about the missing column when some condition in specs were hit, which didn't happen in the original PR but because of splitting I ended up with a newer version of Doorkeeper (which is good, but if I'd realized, I'd tested that better). Somehow the missing column didn't matter when using the API.

[paroga]

i'd go for updating to Doorkeeper5 first and then rebasing all other stuff on top of it

[wvengen]

In hindsight I was too fast merging the earlier PRs ...

[wvengen]

Setup and basic endpoints in #577, updated #572. Will update #573 after feedback.
That's much better, thanks for pointing that out!