It just makes sense to manage your API definitions this way. It's more than just documentation. When you do this, you are taking advantage of the repository and version control features of Github, but you also open things up for participation through forking and pull requests. The resulting definition and machine readable contract can then be injected anywhere into the integration and API lifecycle, internally or externally.

I personally like it when companies manage their API definitions in this way. It gives me a central truth to work with when profiling their operations, something that will be used across my research and storytelling. The more you describe your APIs in this way, the more chance I will be writing about them and including them across my work.