Merge pull request #362 from swagger-api/guidelines

moved here from private repository