It will be nice to have swagger which seems like most commonly use documentation for api which enables auto generating api client.