Merge pull request #387 from obromios/documentation_obromios

Documentation obromios

Author: oestrich

Gemfile.lock

@@ -34,7 +34,7 @@ GEM
       xpath (~> 2.0)
     childprocess (0.5.9)
       ffi (~> 1.0, >= 1.0.11)
-    coderay (1.1.0)
+    coderay (1.1.2)
     contracts (0.13.0)
     crack (0.4.3)
       safe_yaml (~> 1.0.0)
@@ -60,13 +60,13 @@ GEM
     hashdiff (0.2.3)
     httpclient (2.7.1)
     i18n (0.7.0)
-    inch (0.7.0)
+    inch (0.8.0)
       pry
       sparkr (>= 0.2.0)
       term-ansicolor
-      yard (~> 0.8.7.5)
+      yard (~> 0.9.12)
     json (1.8.6)
-    method_source (0.8.2)
+    method_source (0.9.0)
     mime-types (3.0)
       mime-types-data (~> 3.2015)
     mime-types-data (3.2015.1120)
@@ -76,12 +76,11 @@ GEM
     multi_test (0.1.2)
     multipart-post (2.0.0)
     mustache (1.0.3)
-    nokogiri (1.8.1)
+    nokogiri (1.8.4)
       mini_portile2 (~> 2.3.0)
-    pry (0.10.3)
+    pry (0.11.3)
       coderay (~> 1.1.0)
-      method_source (~> 0.8.1)
-      slop (~> 3.4)
+      method_source (~> 0.9.0)
     rack (1.6.4)
     rack-oauth2 (1.2.2)
       activesupport (>= 2.3)
@@ -115,9 +114,8 @@ GEM
       rack (~> 1.5)
       rack-protection (~> 1.4)
       tilt (>= 1.3, < 3)
-    slop (3.6.0)
     sparkr (0.4.1)
-    term-ansicolor (1.3.2)
+    term-ansicolor (1.6.0)
       tins (~> 1.0)
     thin (1.6.4)
       daemons (~> 1.0, >= 1.0.9)
@@ -126,7 +124,7 @@ GEM
     thor (0.19.1)
     thread_safe (0.3.5)
     tilt (2.0.2)
-    tins (1.8.2)
+    tins (1.16.3)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
     webmock (1.22.6)
@@ -135,7 +133,7 @@ GEM
       hashdiff
     xpath (2.0.0)
       nokogiri (~> 1.3)
-    yard (0.8.7.6)
+    yard (0.9.15)
 
 PLATFORMS
   ruby
@@ -147,6 +145,7 @@ DEPENDENCIES
   fakefs (~> 0.4)
   faraday (~> 0.9, >= 0.9.0)
   inch
+  nokogiri (~> 1.8, >= 1.8.2)
   rack-oauth2 (~> 1.2.2, >= 1.0.7)
   rack-test (~> 0.6.2)
   rake (~> 10.1)
@@ -155,6 +154,7 @@ DEPENDENCIES
   sinatra (~> 1.4, >= 1.4.4)
   thin (~> 1.6, >= 1.6.3)
   webmock (~> 1.7)
+  yard (>= 0.9.11)
 
 BUNDLED WITH
-   1.16.1
+   1.16.3

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,106 @@ 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.
+
+## Example of spec file
+
+```ruby
+  # spec/acceptance/orders_spec.rb
+  require 'rails_helper'
+  require 'rspec_api_documentation/dsl'
+  resource 'Orders' do
+    explanation "Orders resource"
+    
+    header "Content-Type", "application/json"
+
+    get '/orders' do
+      # 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}}
+      
+      let(:one_level_array) { ['string1', 'string2'] }
+      let(:two_level_array) { [['123', '234'], ['111']] }
+
+      # This is automatic way
+      # It's possible because we extract parameters definitions from the values
+      parameter :one_level_arr, with_example: true
+      parameter :two_level_arr, with_example: true
+
+      let(:one_level_arr) { ['value1', 'value2'] }
+      let(:two_level_arr) { [[5.1, 3.0], [1.0, 4.5]] }
+
+      context '200' do
+        example_request 'Getting a list of orders' do
+          expect(status).to eq(200)
+        end
+      end
+    end
+
+    put '/orders/:id' do
+
+      with_options scope: :data, with_example: true do
+        parameter :name, 'The order name', required: true
+        parameter :amount
+        parameter :description, 'The order description'
+      end
+
+      context "200" do
+        let(:id) { 1 }
+
+        example 'Update an order' do
+          request = {
+            data: {
+              name: 'order',
+              amount: 1,
+              description: 'fast order'
+            }
+          }
+          
+          # It's also possible to extract types of parameters when you pass data through `do_request` method.
+          do_request(request)
+          
+          expected_response = {
+            data: {
+              name: 'order',
+              amount: 1,
+              description: 'fast order'
+            }
+          }
+          expect(status).to eq(200)
+          expect(response_body).to eq(expected_response)
+        end
+      end
+
+      context "400" do
+        let(:id) { "a" }
+
+        example_request 'Invalid request' do
+          expect(status).to eq(400)
+        end
+      end
+      
+      context "404" do
+        let(:id) { 0 }
+        
+        example_request 'Order is not found' do
+          expect(status).to eq(404)
+        end
+      end
+    end
+  end
+```
 
 
 ## Configuration options
@@ -306,9 +407,7 @@ paths:
       description: This description came from configuration file
       hide: true
 ```
-
-#### Example of spec file
-
+#### Example of spec file with :open_api format
 ```ruby
   resource 'Orders' do
     explanation "Orders resource"

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"

rspec_api_documentation.gemspec

@@ -30,6 +30,8 @@ Gem::Specification.new do |s|
   s.add_development_dependency "rspec-its", "~> 1.0"
   s.add_development_dependency "faraday", "~> 0.9", ">= 0.9.0"
   s.add_development_dependency "thin", "~> 1.6", ">= 1.6.3"
+  s.add_development_dependency "nokogiri", "~> 1.8", ">= 1.8.2"
+  s.add_development_dependency "yard", ">= 0.9.11"
 
   s.files        = Dir.glob("lib/**/*") + Dir.glob("templates/**/*")
   s.require_path = "lib"