API Documentation

Overview

The API documentation is generated by rspec_api_blueprint. To support the syntax used by MyUSA, we are using a fork of rspec_api_blueprint from petrbela in the feat/markdown branch.

Prerequisites

Install gems

You will need the development or test bundle installed. The easiest way:

bundle install

Install Aglio

The API documentation relies on Aglio to compile and generate static HTML.

npm install -g aglio

How to write and generate documentation

The API documentation is generated from rspec test files and the Rails controllers. By modifying these files, API documentation can be automatically generated.

To generate the API doc, each API rspec test needs to start with a describe Group 'ControllerClass' with each individual test starting with a describe GET/POST/PUT 'url'. Additional information for each test is included in the controller by starting the comment group with the describe url of the rspec test.

After the controller and rspec files are modified, the rspec tests must be run. This will generate blueprint .md files in the /api_docs folder.

Then the documentation html file is generated from a script that will combine an introductory markdown file (public/developer/api_doc.md) and every blueprint markdown file in the /api_docs directory and render the markdown into html using Aglio.

rake make_api_html

The following is an example from the code for the Profile API.

In the spec test file is:

  describe "Group Profile" do
    before do
       @token = build_access_token(@app)
    end
    describe "GET /api/profile?schema=" do
      it "Get the user profile with limited attributes, schema true" do
        response = get "/api/profile", {"schema" => "true"}, {'HTTP_AUTHORIZATION' => "Bearer #{@token}"}
        expect(response.status).to eq 200
      end
    end
    describe "GET /api/profile" do
      it "Get the user profile with all attributes" do
         response = get "/api/profile", nil, {'HTTP_AUTHORIZATION' => "Bearer #{@token}"}
         expect(response.status).to eq 200
      end
    end
  end

In the controller is:

  #GET /api/profile?schema=
  #
  #Get the user profile with attributes limited to just those chosen by app owner
  #during app registration in schema format.
  #
  # + Parameters
  #
  #  + schema (required, boolean, `true`)
  
  #GET /api/profile
  #
  #Get the user profile with attributes limited to just those chosen by app owner
  #during app registration.

These additions to the controller and rspec file produce the following markdown file after running the rspec test:

# Group Profile

## GET /api/profile?schema=

Get the user profile with attributes limited to just those chosen by app owner
during app registration in schema format.

+ Parameters

 + schema (required, boolean, `true`)

+ Response 200 (application/json; charset=utf-8)

    {
      "email": "joe@citizen.org",
      "givenName": "Joe",
      "additionalName": null,
      "familyName": "Citizen",
      "homeLocation": {
        "streetAddress": "",
        "addressLocality": null,
        "addressRegion": null,
        "postalCode": null
      },
      "telephone": null,
      "gender": null
    }

## GET /api/profile

Get the user profile with attributes limited to just those chosen by app owner
during app registration.

+ Response 200 (application/json; charset=utf-8)

    {
      "title": null,
      "first_name": "Joe",
      "middle_name": null,
      "last_name": "Citizen",
      "suffix": null,
      "address": null,
      "address2": null,
      "city": null,
      "state": null,
      "zip": null,
      "gender": null,
      "marital_status": null,
      "is_parent": null,
      "is_student": null,
      "is_veteran": null,
      "is_retired": "0",
      "email": "joe@citizen.org",
      "phone_number": null,
      "mobile_number": null,
      "uid": "4c108bd5-2042-421b-b09f-4a004dbd441d",
      "id": "4c108bd5-2042-421b-b09f-4a004dbd441d"
    }

The rendered markdown looks like this: