You can publish documentation on hosted platforms specifically built for API and developer documentation. Two promising platforms are the following:
If you consider how much time it requires to build, maintain, troubleshoot, etc. your own website, then it really does make sense to consider an existing third-party platform where someone has already built all of this out for you.
In this tutorial we’ll explore how to publish content on readme.io in more depth.
In this workshop activity, you’ll publish this weatherdata endpoint documentation on readme.io.
Add a Project Name (e.g., Weather API), Subdomain (e.g., weather-api), and Project Logo. Then click Create Project.
In the left sidebar, under Settings, click API Settings.
This is where you add the authentication information necessary for making calls to the API.
In the Static Headers section, click Add Header add these two headers as key-value pairs in the appropriate fields:
X-Mashape-Key APIKEY Accept application/json
Add in the documentation from the weatherdata endpoint documentation. For example, add the description, parameters, cURL call, and response.
In the Try It Out section, insert some values into the lat and lng fields, and then click Try It.
The experience is similar to Swagger in that the response appears directly in the documentation. This API Explorer gives you a sense of the data returned by the API.
Readme.io is a pretty sweet platform, and you don’t have to worry about describing your API based on a specification based on either RAML or Swagger. But this also has downsides. It means that your doc is tied to the Readme.io platform. Additionally, you can’t auto-generate the output from annotations in your source code.
Additionally, if the cloud location for your docs isn’t an option, that may also pose challenges. Finally, there isn’t any content re-use functionality, so if you have multiple outputs for your documentation that you’re single sourcing, Readme.io may not be for you.
Even so, the output is sharp and the talent behind this site is top-notch. The platform is constantly growing with new features, so maybe all of this functionality will eventually be there.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson