Add v2 & v3 API documentation

Keystone itself didn't have much documentation on the APIs it was
implementing, so I made space for that documentation first, and then
followed it with a first pass on what it takes to move things to v3.

Change-Id: I71ee6d3c87b6919eb2f7569069d91f3a00d6337c
bp: document-v2-to-v3-transition
Merge "Add v2 & v3 API documentation"