Investigate API Blueprint gem for auto-generating API documentation

[polastre]

This may require modification of the gem to generate docs using the same format that we use.

[RyanRusnak]

rspec_api_blueprint is a ruby gem that hooks into rspec tests and generates json/markdown based on the success and failure of those tests. Example:

 it "should return an error and message" do
          response = get "/api/profile", nil, {'HTTP_AUTHORIZATION' => "Bearer #{@token}"}
          expect(response.status).to eq 403
          parsed_json = JSON.parse(response.body)
          expect(parsed_json["message"]).to eq "You do not have permission to read that user's profile."
end

The above test will automatically generate:

# GET /api/profile
+ Response 200 text/plain

This is great since we can create a dynamic interface that shows the passing and failing of our rspec tests with no additional work. However, we are using aglio to generate our API docs which requires a different format. The below snippet if from our API markdown that generates the myusa docs. You can see that it requires additional information to specify the format and has a more complex markdown hierarchy. The gem will have to be forked and modified in one of two ways. Our first option is to pass it a template and have it populate certain values. The second is to increase the functionality of the gem and enable to generate additional tags based on our tests. Neither of these are a low lift, but will provide us a mostly automated solution documentation of our tests.

FORMAT: 1A
HOST: https://myusa.gov/developers/api

# MyUSA API Documentation

# Group Authentication
# Getting started with MyUSA Authentication

MyUSA uses OAuth 2.0. To find out more information about MyUSA and how to create your own application visit the [developers](https://my.usa.gov/developer) section of MyUSA.

## Overview

1. Your application redirects the user to a login dialog at the MyUSA.gov.

### Scopes

## Your Application

First start by adding this gem to your Gemfile:

gem 'omniauth-myusa', :git => 'https://github.com/GSA-OCSIT/omniauth-myusa.git'

The scopes you define when you setup your app on MyUSA.gov define what information your app will require from the user. Scopes limit access for OAuth tokens. They do not grant any additional permission beyond that which the user already has.

[RyanRusnak]

Note: apparently github parses markdown so that comment will not make a lot of sense. Are you able to view the raw comment?

[polastre]

No, I can't see the raw. Did you put it in triple backquotes? (```)

[RyanRusnak]

much better now!

[adam-at-mobomo]

We can investigate this pull request: calderalabs/rspec_api_blueprint#9

[adam-at-mobomo]

Also, as-is the https://github.com/playround/rspec_api_blueprint gem throws a warning in RSpec 3.0. It should be updated to no longer rely on the :example_group:

Deprecation Warnings:

The :example_group key in an example group's metadata hash is deprecated. Use the example group's hash directly for the computed keys and :parent_example_group to access the parent example group metadata instead. Called from /Users/adam/workspace/MyGov/myusa-server/vendor/bundle/gems/rspec_api_blueprint-0.0.8/lib/rspec_api_blueprint.rb:30:in `yield'.

If you need more of the backtrace for any of these deprecations to
identify where to make the necessary changes, you can configure
config.raise_errors_for_deprecations!, and it will turn the
deprecation warnings into errors, giving you the full backtrace.

[jackiekazil]

should be thought about in #640