Swagger is a decent middle ground. There's a lot of warts, but it's serviceable and fairly prevalent with implementations in a variety of languages. Mainly I li

Swagger is a decent middle ground. There's a lot of warts, but it's serviceable and fairly prevalent with implementations in a variety of languages. Mainly I like to use the yaml version to quickly communicate rest api's. I've also recently started appreciating JSON Schema more recently for this reason. It's lighter weight than xml schemas. Inclusion of regex based field validation is pretty handy.