Swagger is becoming an accepted standard in API documentation.
http://swagger.io/
Tools like Postman include the ability to import Swagger definitions.

A Symfony bundle already exists that provides this functionality.
https://github.com/nelmio/NelmioApiDocBundle

As an API developer, I'd like to view and use the Swagger specification so that I can import API definitions into Postman and similar tools.

As an API developer, I'd like to view and use the Swagger specification so that I can use the Swagger UI to understand what API endpoints are available, what fields are available and required, and also test the endpoint using the Swagger UI.