Recently, I came across the need of providing some sort of documentation for an API I was building. At that moment, I had never heard of the API Blueprint specification. Though they might be several options to write a good API documentation, I found this one to be very helpful for the following reasons.

1. Easy to read

Sections are well defined and grouped by route. Each route can have several different HTTP methods with names associated to each method. The documentation shows:

1. Attributes listed with their descriptions (when needed)
2. Requests examples (headers and body)
3. Responses of those examples (also headers and body)

See more.

2. Mock server

This language allows you to create a mock server that anyone can use to test the response of the actual server (there are tools for this, see more.)

So the mock server is actually a server that responds to the endpoints defined in the documentation and returns the expected responses (it does not care about authentication or headers, cause it actually does not run the production code, it just returns the response to the endpoint hit). So it's very helpful to have this kind of server in the early stages of an app, where the client application is still being built and the backend is not fully deployed to a production/testing cloud based environment.

3. Lots of tools

Renderers are services that take your blueprint as input and create a nice web page for others to refer to, when using you API. Apiary is one of them, and a widely used one. Apiary can be connected with your remote repository, so whenever you blueprint changes, it will automatically reflect the changes in the documentation page.

But I don't want to write another language, and probably neither do you. So here's where docs-generator libraries take place. For those using Ruby❤️, RSpec API documentation turned out to be a great tool to generate this blueprint (though it can be used to generate other type of docs). You just need to write some RSpec tests and run a rake task to generate the blueprint.

Here's an example of a basic endpoint being documented using this gem:

resource 'Books' do
  before do
    create_list :book, 5                # Creating some books 
  end

  route '/books', 'Books collection' do # Name of the section
    get 'Index' do                      # HTTP method with name
      example 'Ok' do                   # A request example
        do_request

        expect(status).to eq 200        # Basic expectation of the request
      end
    end
  end
end

After running rails docs:generate it'll generate a file with something like this:

# Group Books

## Books collection [/books]

### Index [GET]

+ Request Ok

+ Response 200 ()

    + Body

            {
              ... // The response body would be here
            }

If you are writing an API give this language a try. Make your fellow developers happy by giving them a proper documentation of your API.

To sum up, some things I like about it

1. Production code does not get mixed with the doc-generating code
2. All documentation related code lives in one place
3. As soon as a change is made in routes or in the response of the controllers the documentation gets updated automatically by the generator. I don't need to write anything new.
4. Mock server just uses the data from the docs (it does not run the production code)
5. There are bunch of services to render the documentation (renderers) or I can host my own 😎
6. My API blueprint file lives in the same repository, so I can assure it's always synced with the current branch

_{In case you want to look a full set of doc-generating test examples}