New York Times Manages Their OpenAPI Using Github01 Mar 2017
I come across more companies managing their OpenAPI definition as a single Github repository. One example of this is from the New York Times, who as the API definitions for their platform available as its own Github repository. It demonstrates the importance of maintaining your API definitions separately from any particular implementation, such as just your documentation.
You can find Individual OpenAPIs for their archive_api, updated description, article_search,books_api, community, geo_api, most_popular_api, movie_reviews, semantic_api, times_tags, timeswire, top_stories broken down into separate folders within the Github repository. The NYT also provides markdown documentation, alongside the machine-readable OpenAPI definition in each folder, helping make sure things are human-readable.
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.