Follow-up from "Update API docs"

The following discussion from !2031 (merged) should be addressed:

@georgkrause started a discussion: (+2 comments)

Unfortunately we can't import the document into the Swagger file, so I think the best thing to do would be to list the essential information in swagger:

What flow do we use (plus link to the spec) What are our endpoints? A link to the full flow in the docs hub