Choosing a tool to document the OpenROV APIs


#1

Documenting the APIs for the OpenROV has been an often made request and one I’d like to fill. I’ve been looking high and low to find a tool to document the APIs. Do you have experience with a documentation system that both created useful documentation and was nice enough to work with that it was kept up to date? I have some thoughts on what the tools should be able to do:

  1. Killer search
  2. Support example usage in multiple languages
  3. Ability to allow testing of the API for real without having to code
  4. Be readable

Killer search

APIs have layers of concepts in the documentation. The killer search makes it easy to focus your search in the area your interested. The example below need to give us relevant results for a coder:
example login ruby
yaw command
handling error messages

Support Examples in multiple languages

I like supporting whatever language makes the developer productive. That means relevant code examples. It turns out that the libraries you need to access Socket.io from different languages very a lot. Having code that a Ruby programmer can access that shows how to integrate a library they don’t commonly use will make them more likely to try it out. Auth0 does this by providing lots of example applications, the Slate documentation platform does this with inline examples along side the documentation.

Slate documentation with tabs to select examples

Auth0 build your own example selector screen

Ability to allow testing of the API for real without having to code

I think this feature is probably the most important feature in selecting a documenation platform today, because it gives us a way to automate the execution of the examples to ensure they are all still working and correct between software releases. A couple of years back I started seeing this trend of documentation as a test application. This means you can test against your actual test instance of a service by either cutting and pasting working code examples in to runtime environments like a shell to execute curl scripts or a site like jsfiddle for javascript code, or there would be buttons in the documentation to let you run the examples in place. The key in both cases is that the examples would pull credentials or api keys needed from your account and inject them in to the examples in the documentation so they would run as is. Any issues we find likely point to pages of documentation that need to be updated. Swagger seems to be the library that is powering this feature in documentation everywhere I look.

Swagger example API documentation site

Swagger even powers Marvel’s API documentation… Marvel has an API!

Be readable

I find this hard for documentation. It needs to allow you to scan it, dive deep in to a particular call’s details, and to understand the application protocol (the combination of calls and responses needed to get work done). Can’t say I’ve come across any examples yet that knock my socks of. You?


Feature: API Documentation