Documentation obromios

README.md

@@ -60,6 +60,10 @@ Consider adding a viewer to enhance the generated documentation. By itself rspec
 
     gem 'raddocs'
 
+    or 
+
+    gem 'apitome'
+
 #### spec/spec_helper.rb
 
 ```ruby
@@ -68,9 +72,18 @@ RspecApiDocumentation.configure do |config|
 end
 ```
 
+####
+For both raddocs and apitome, start rails server. Then
+
+    open http://localhost:3000/docs for raddocs
+
+    or
+
+    http://localhost:3000/api/docs for apitome
+
 ## Sample App
 
-See the `example` folder for a sample Rails app that has been documented.
+See the `example` folder for a sample Rails app that has been documented.  The sample app demonstrates the :open_api format.
 
 
 ## Configuration options
@@ -307,21 +320,18 @@ paths:
       hide: true
 ```
 
-#### Example of spec file
+## Example of acceptance spec file
 
 ```ruby
+  # spec/acceptance/orders_spec.rb
+  require 'rails_helper'
+  require 'rspec_api_documentation/dsl'
   resource 'Orders' do
     explanation "Orders resource"
 
-    authentication :apiKey, :api_key, description: 'Private key for API access', name: 'HEADER_KEY'
     header "Content-Type", "application/json"
-
-    let(:api_key) { generate_api_key }
 
     get '/orders' do
-      route_summary "This URL allows users to interact with all orders."
-      route_description "Long description."
-
       # This is manual way to describe complex parameters
       parameter :one_level_array, type: :array, items: {type: :string, enum: ['string1', 'string2']}, default: ['string1']
       parameter :two_level_array, type: :array, items: {type: :array, items: {type: :string}}
@@ -340,13 +350,11 @@ paths:
       context '200' do
         example_request 'Getting a list of orders' do
           expect(status).to eq(200)
-          expect(response_body).to eq(<response>)
         end
       end
     end
 
     put '/orders/:id' do
-      route_summary "This is used to update orders."
 
       with_options scope: :data, with_example: true do
         parameter :name, 'The order name', required: true
@@ -377,7 +385,7 @@ paths:
             }
           }
           expect(status).to eq(200)
-          expect(response_body).to eq(<response>)
+          expect(response_body).to eq(expected_response)
         end
       end
 

example/Gemfile

@@ -6,7 +6,7 @@ gem 'rack-cors', :require => 'rack/cors'
 gem 'rails', '4.2.5.1'
 gem 'sqlite3'
 gem 'spring', group: :development
-gem 'raddocs', :github => "smartlogic/raddocs"
+gem 'raddocs', '0.4.0'
 
 group :test, :development do
   gem 'byebug'

example/Gemfile.lock

@@ -1,12 +1,3 @@
-GIT
-  remote: git://github.com/smartlogic/raddocs.git
-  revision: 9cf49c1ef3b3d7dc3bf8e19ef75021040df04652
-  specs:
-    raddocs (0.4.0)
-      haml (~> 4.0, >= 4.0.4)
-      json (~> 1.8, >= 1.8.1)
-      sinatra (~> 1.3, >= 1.3.0)
-
 PATH
   remote: ..
   specs:
@@ -62,7 +53,7 @@ GEM
     erubis (2.7.0)
     globalid (0.3.6)
       activesupport (>= 4.1.0)
-    haml (4.0.5)
+    haml (4.0.7)
       tilt
     i18n (0.7.0)
     json (1.8.3)
@@ -78,10 +69,14 @@ GEM
       mini_portile2 (~> 2.0.0.rc2)
     rack (1.6.4)
     rack-cors (0.4.1)
-    rack-protection (1.5.3)
+    rack-protection (1.5.5)
       rack
     rack-test (0.6.3)
       rack (>= 1.0)
+    raddocs (0.4.0)
+      haml (~> 4.0, >= 4.0.4)
+      json (~> 1.8, >= 1.8.1)
+      sinatra (~> 1.3, >= 1.3.0)
     rails (4.2.5.1)
       actionmailer (= 4.2.5.1)
       actionpack (= 4.2.5.1)
@@ -127,10 +122,10 @@ GEM
       rspec-mocks (~> 3.0.0)
       rspec-support (~> 3.0.0)
     rspec-support (3.0.4)
-    sinatra (1.4.5)
-      rack (~> 1.4)
+    sinatra (1.4.8)
+      rack (~> 1.5)
       rack-protection (~> 1.4)
-      tilt (~> 1.3, >= 1.3.4)
+      tilt (>= 1.3, < 3)
     spring (1.1.3)
     sprockets (3.5.2)
       concurrent-ruby (~> 1.0)
@@ -142,7 +137,7 @@ GEM
     sqlite3 (1.3.9)
     thor (0.19.1)
     thread_safe (0.3.5)
-    tilt (1.4.1)
+    tilt (2.0.8)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
 
@@ -153,7 +148,7 @@ DEPENDENCIES
   awesome_print
   byebug
   rack-cors
-  raddocs!
+  raddocs (= 0.4.0)
   rails (= 4.2.5.1)
   rspec-rails
   rspec_api_documentation!
@@ -164,4 +159,4 @@ RUBY VERSION
    ruby 2.3.3p222
 
 BUNDLED WITH
-   1.16.2
+   1.16.3

example/spec/acceptance_helper.rb

@@ -3,7 +3,7 @@
 require 'rspec_api_documentation/dsl'
 
 RspecApiDocumentation.configure do |config|
-  config.format = [:open_api]
+  config.format = [:open_api, :html]
   config.curl_host = 'http://localhost:3000'
   config.api_name = "Example App API"
   config.api_explanation = "API Example Description"