For one of our clients we built an API driven platform which could be consumed in two ways, either as a service using our front end or by integrating third party UI interfaces with the API. As one could guess API documentation plays a vital role in usability of such systems. We use ServiceStack as our web services framework and API documentation generation is built into the framework. The generated documentation is a JSON file that conforms to Open API, which is a specification and complete framework implementation for describing, producing, consuming, and visualizing restful web services.
When creating API for consumption by third party developers it is always important to document them. The task of creating API documentation may not be trivial but its fairly doable considering the tools available but the task of maintaining them seems to where the product teams fall short more often than not. All seems perfect at the launch of version 1 of the API with neat and clear documentation complementing the efficient API’s that you have so arduously built.