Suggested improvements to usergrid.yaml

[earth2marsh]

Great progress! Here are some observations (big and small) about things that would improve the description.

1. Change all instances of UserGrid to Usergrid, as the G should not be capitalized (including the filename)
2. Since schemas refer to definition keys, recommend removing the spaces, for example, Action Response Info might become ActionResponseInfo
3. Consider names of things, like UserInfo might be more succinct as User or ActionResponseInfo might be Action (important to think through the semantics, even of these examples)
4. parameters can now be defined as a peer of definitions. @jwest-apigee knows more about this.
5. Consistent casing of descriptions, see https://github.com/apigee-127/usergrid-swagger/blob/master/UserGrid.yaml#L42 for one that begins with lowercase. Recommend uppercase for all.
6. Try not to use the verb in the description of the operation. For example, Use the GET method to retrieve details about an admin user could be expressed as, Retrieve details about an admin user https://github.com/apigee-127/usergrid-swagger/blob/master/UserGrid.yaml#L65
7. As a property, use uuid, but in docs, use UUID. https://github.com/apigee-127/usergrid-swagger/blob/master/UserGrid.yaml#L69
8. Is it valid to use a | in a path? Need to check. See: https://github.com/apigee-127/usergrid-swagger/blob/master/UserGrid.yaml#L316
9. Reconsider tag names, such as Credential Info to be as accurate and succinct as possible https://github.com/apigee-127/usergrid-swagger/blob/master/UserGrid.yaml#L520