I've been pushing for better API design tooling for some time now, something that significantly overlaps with movements I would also like to see around API documentation as well. In my opinion, we have made significant strides with the introduction of Swagger UI, as well as pushed the API documentation conversation to be part of the API design process by Apiary. This is something that was further re-enforced with the evolution of Swagger UI to be part of the Swagger Editor toolkit--where Swagger UI was used in real-time as part of the API design process, not just later down the road as API documentation for consumers.
This demonstrates for me the importance of API documentation, not just in helping API consumers understand what an API does at integration time, but also for API providers at design, mock, test, and any other time during the API lifecycle. Functional, attractive looking, and often interactive documentation that describes what an API does is needed from design to deprecation, and is an area of the API world that I feel is pretty underserved at the moment.
Swagger UI is a 100% client side JavaScript solution, which if you've ever cracked open the code, know that it cannot be used as a base template to move this conversation forward. The more attractive Slate solution is appealing right up until you realize it doesn't perpetuate the machine readable API core we will need to successfully integrate with every other stop along the API lifecycle. I haven't seen any movement out the efforts to make an OpenAPI Spec driven Slate, but I am pleased with the movements by Lucybot in their Lucybot Console. These are moving the needle a little bit but won't get us far down the road when it comes to API documentation that can be used across all stops along the lifecycle without friction.
We will need API documentation that can be published in web, mobile, and desktop solutions that are serving the API community. It needs to be easily embeddable, on any platform, and help API designers, architects, consumers, analysts, and anyone else with a stake in the outcome understand what the hell is going on. We need our API documentation to be plug and play in our API portals like Swagger UI has been. We need API documentation to be a driver of the API design and mock conversations like Apiary has injected. We need it to drive other areas of API management like Gelato and Readme are doing, or other areas of the API lifecycle like APIMATIC is doing for helping us managing SDKs.
We need a 100% client-side solution, as well as a diverse range of supercharged server and desktop solutions, that can be used across the API life cycle, whether supporting creation or consumption. We need an open source solution run by a benevolent dictator (not it), who will help ensure its platform agnostic, and has a fully customizable UI and styling, which can be embedded into leading API services and tooling, helping standardize the documentation for each area of the API lifecycle. We need the next steps in the evolution of API documentation, and visualization to be set into motion in 2016.
