fdoc: an API Documentation Tool

Written by Zach Margolis.

**fdoc** is a tool we’ve built to help us maintain our API documentation. It provides a schema for our endpoints and a central place for documentation. We’re really excited to open source fdoc today.

We use fdoc for two things:

1. A machine-readable file format to describe an API, with a script to generate human-readable HTML pages.

2. Failing our specs when undocumented parameters are detected.

Background

For a long time, we kept our API documentation in an internal wiki so our server, iOS and Android teams could keep in sync. As the code evolved, the wiki would often lag, and our teams would get out of sync.

Most engineers that used the API have a war story or two related to when somebody was not up to date with somebody else. To call our documentation a “pain point” would be an understatement. Recently, even our client-side Javascript teams have started to use the same APIs, making an even stronger case for having up-to-date documentation.

During one of our company-wide Fix-it Weeks a few months back, we prototyped an early version of fdoc and have been iterating ever since.

Goals

At the outset, we established a set of goals that we wanted from our documentation tooling.

• Client engineers should be able to participate in documenting an API and keeping it up to date.

• Server engineers should be able to test their implementations.

• The documentation should be as close to the code as possible.

• Branches, reviews, and merges are the appropriate way to update the docs.

• Experimental drafts should just live on branches and never get merged into master.

• Specification alone is not enough, there needs to be room for discussion.

In our experience thus far, fdoc accomplishes these.

How it Works

fdoc cobbles together a handful of available technologies to realize its goals:

• YAML, for raw files that are pretty easy to read and edit.

• JSON Schema, a fairly robust and flexible way to describe JSON objects, with validation provided by hoxworth’s json-schema gem.

• Markdown for a clean, expressive way to write descriptions, parsing provided by the kramdown gem.

We wrote a helper that you can include in Rails controller specs that intercepts calls to get, post, put and delete to verify request and response parameters.

require 'fdoc/spec_watcher'

describe MembersController do
  include Fdoc::SpecWatcher

  context "#show", :fdoc => 'members/list' do
    it "can order by name" do
      get :show, {
        :limit    => 5,
        :order_by => "name"
      }
    end
  end
end

This same helper has what we call “scaffolding” mode (triggered by the FDOC_SCAFFOLD=true environment variable), where fdoc will compose a schema based on its input. It creates an incredibly easy way to bootstrap API documentation.

FDOC_SCAFFOLD=true bundle exec rspec spec/controllers

We also wrote fdoc_to_html, a simple script to create a static HTML version of .fdoc files for easy browsing.

Today

Across all of our internal services, we have about 65 endpoints documented with fdoc. Since these are verified by our tests, all of our client engineers can trust that they have up-to-date and accurate documentation.

Again, we’re excited to share fdoc with the world, in the hope that others can benefit from its utility. Please, check out fdoc on Github! Zach Margolis (@zachmargolis) | Twitter The latest Tweets from Zach Margolis (@zachmargolis). Full-time hustler, part-time rhymertwitter.com