Conform Swagger documentation to best practices

[bdemchak]

The existing Swagger documentation is usable for someone that already knows what it says. Best practices focuses on users who do and don't know this.