Problem

I work on a team that consists of 10+ hardware/firmware engineers, a few data scientists and a few iOS engineers. Firmware, iOS and data science teams all need to use my code (private API). I therefore need to document the API well.

The trouble is, I almost always forget to update the docs. I am OK at remembering to document new endpoints that I've added, but the smaller things which are more removed from the API are the ones that have been the worst for consistency (eg. if I update the db schema to add/remove field from db table + go type, I never remember to update the docs for the API endpoints that rely on this type)

I eventually forked dredd to periodically test our API for mistakes, but our API was still inconsistent most of the time.

Solution

I always remember to write go tests for my API endpoints.. and they are usually fairly thorough. These tests do run through multiple scenarios for every endpoint. So what if I could just capture the request and response for each test, and make the machine rewrite my documentation file for me given this captured data.

So I've built a simple testing framework (ish) that will wrap your golang test server, record the requests/responses and write to your documentation file in the appropriate format (API Blueprint -- see below).

The generated file is not currently 100% finished/valid, but it's getting there! The framework can be found at github.com/gophergala/test2doc, example code is at github.com/gophergala/test2doc/example, example generated file would be github.com/gophergala/test2doc/apiary.apib

Background

  1. I use API Blueprint for our API documentation format (fairly new API documentation standard)
  2. I use apiary.io to parse our documentation file (hosted on github) and generate a beautiful, interactive API documentation tool for my teammates to reference:

raw

generated

Team

Sarah Adams github: adams-sarah

Share this project:
×

Updates