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.
Self-hosting documentation securely for an API platform with granular control on who can see what using filter policies
Requirements Recently we've embarked on an adventure to move online documentation of an API platform for one of our clients from ReadMe to a self-hosted solution chiefly to provide granular access control capability required by the business. Self-hosting of documentation has two main elements: Endpoints – This is the API reference section with OpenAPI specification for each endpoint Articles – This section contains how-tos and other articles related to the system, workflows and security.
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.