API documentation is the number one pain point for developers trying to understand what is going on with an API, as they work to get up-and-running, consuming the resources they possess. From many discussions I’ve had with API providers, it is also a pretty big pain point for many API developers when it comes to trying to keep up to date, and delivering value to consumers. Thankfully, API documentation has been being driven by API definitions like OpenAPI for a while, helping keep things up to date and in sync with changes going on behind the scenes. The challenge for many groups who are only doing OpenAPI to produce documentation, is that if the OpenAPI isn’t used across the API lifecycle, it will often be forgotten, recreating that timeless challenge with API documentation.
Thankfully, in the last year or so, I’m beginning to see more API documentation solutions emerge, getting us beyond the Swagger UI age of docs. Don’t get me wrong, I’m thankful for what Swagger UI has done, but, then, I’m finding it to be very difficult to get people beyond the idea that OpenAPI (formerly known as Swagger) isn’t the same thing as Swagger UI, and that the only reason you generate API definitions is to get documentation. There are a number of API documentation solutions to choose from in 2018, but Swagger UI still remains a viable choice for making sure your APIs are properly documented for your consumers. https://goo.gl/UiWAo5 #DataIntegration #ML
