Start filling out the documentation

README.md

 # RSpec Swagger
 
 [![Build Status](https://travis-ci.org/drewish/rspec-swagger.svg?branch=master)](https://travis-ci.org/drewish/rspec-swagger)
+[![Code Climate](https://codeclimate.com/github/drewish/rspec-swagger/badges/gpa.svg)](https://codeclimate.com/github/drewish/rspec-swagger)
 
-The design of this is heavily influenced by the awesome [swagger_rails](https://github.com/domaindrivendev/swagger_rails) gem.
+This gem helps you generate Swagger docs by using RSpec to document the paths.
+You execute a command to run the tests and generate the `.json` output. Running
+the tests ensures that your API and docs are in agreement, and generates output
+that can be used as examples.
+
+The design of this was heavily influenced by the awesome [swagger_rails gem](https://github.com/domaindrivendev/swagger_rails).
 
 ## Setup
 
-- install gem
-- `rails generate rspec:install`
-- create `spec/swagger_helper.rb` (I'll try to get a generator to automate this)
-- define your tests (I definitely need to make this step more explicit)
+- Add the gem to your Rails app's `Gemfile`:
+```
+group :development, :test do
+  gem 'rspec-swagger'
+end
+```
+- If you don't already have a `spec/rails_helper.rb` file run:
+```
+rails generate rspec:install
+```
+- Create `spec/swagger_helper.rb` file (eventually this will become a generator):
+```
+require 'rspec/swagger'
+require 'rails_helper'
+
+RSpec.configure do |config|
+  # Specify a root directory where the generated Swagger files will be saved.
+  config.swagger_root = Rails.root.to_s + '/swagger'
+
+  # Define one or more Swagger documents and global metadata for each.
+  config.swagger_docs = {
+    'v1/swagger.json' => {
+      swagger: '2.0',
+      info: {
+        title: 'API V1',
+        version: 'v1'
+      }
+    },
+    'v2/swagger.json' => {
+      swagger: '2.0',
+      info: {
+        title: 'API V2',
+        version: 'v2'
+      }
+    }
+  }
+end
+```
+- Define your API (I definitely need to make this step more explicit)
 
 ## Generate the docs
 
+Eventually this will become a rake task:
 ```
 bundle exec rspec -f RSpec::Swagger::Formatter --order defined -t swagger_object
 ```
 
-
 ## Running tests
 
-Set up a test site for a specific version of Rails:
+The `make_site.sh` script will create a test site for a specific version of
+Rails:
 ```
 RAILS_VERSION=4.2.0
 ./make_site.sh

rspec-swagger.gemspec

@@ -5,7 +5,7 @@ Gem::Specification.new do |s|
   s.name        = 'rspec-swagger'
   s.version     = RSpec::Swagger::Version::STRING
   s.licenses    = ['MIT']
-  s.summary     = "Generate Swagger docs from rspec integration tests"
+  s.summary     = "Generate Swagger docs from RSpec integration tests"
   s.description = "Inspired by swagger_rails"
   s.author      = "andrew morton"
   s.email       = 'drewish@katherinehouse.com'