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:
- Killer search
- Support example usage in multiple languages
- Ability to allow testing of the API for real without having to code
- Be readable
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
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
Swagger example API documentation site
Swagger even powers Marvel’s API documentation… Marvel has an API!
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?