From 0c3d3282258b75cb5f9784731c8f55a1221c5947 Mon Sep 17 00:00:00 2001 From: Chris Drane Date: Mon, 30 Jul 2018 14:30:15 +1000 Subject: [PATCH 1/7] Change declaration in gemfile for raddocs The gemfile had gem 'raddocs', :github => "smartlogic/raddocs" which loads over http not https so is insecure. --- example/Gemfile | 2 +- example/Gemfile.lock | 29 ++++++++++++----------------- 2 files changed, 13 insertions(+), 18 deletions(-) diff --git a/example/Gemfile b/example/Gemfile index 53112786..cacf5aff 100644 --- a/example/Gemfile +++ b/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' diff --git a/example/Gemfile.lock b/example/Gemfile.lock index 32919b0f..fd2e4eef 100644 --- a/example/Gemfile.lock +++ b/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 From ab3c6b7e9192ae874b471a47befcd0ea89c4c9ac Mon Sep 17 00:00:00 2001 From: Chris Drane Date: Tue, 31 Jul 2018 11:04:03 +1000 Subject: [PATCH 2/7] Add :html option to config.format in acceptance_helper At present, only option is :open_api, but this does not produce output that is easily readable by user. When the problem with the :json option is fixed see issue https://github.com/zipmark/rspec_api_documentation/issues/382 I suggest that :json option is added as well, users can see output using raddocs. --- example/spec/acceptance_helper.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/example/spec/acceptance_helper.rb b/example/spec/acceptance_helper.rb index af483744..7b4e69f4 100644 --- a/example/spec/acceptance_helper.rb +++ b/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" From 7742d4a93ad839a520837d35f3fb2ca27fc0039a Mon Sep 17 00:00:00 2001 From: Chris Drane Date: Tue, 31 Jul 2018 11:25:06 +1000 Subject: [PATCH 3/7] Make README documentation clearer for Viewers section --- README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/README.md b/README.md index d1e02947..a8b89c75 100644 --- a/README.md +++ b/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,6 +72,15 @@ 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. From eb9079c2d90f08c96608cf1e136f822d6d76e650 Mon Sep 17 00:00:00 2001 From: Chris Drane Date: Tue, 31 Jul 2018 11:53:04 +1000 Subject: [PATCH 4/7] Alter example spec section This has been altered to take out any open_api code. Given there is only one example spec in the README document, my view is that it should not be specifically open_api, but just use the most general options. I have bumped the level of this section up by two levels, as it no longer fits under the open_api section of the format section. I have also taken out or re-factored instances of , given I could not understand what the code did in this instance. I note that the example code in the repository is open_api, so there is already an example of open_api code. --- README.md | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index a8b89c75..2150c5ec 100644 --- a/README.md +++ b/README.md @@ -320,21 +320,16 @@ paths: hide: true ``` -#### Example of spec file +## Example of acceptance spec file ```ruby + # spec/acceptance/orders_spec.rb 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}} @@ -353,13 +348,11 @@ paths: context '200' do example_request 'Getting a list of orders' do expect(status).to eq(200) - expect(response_body).to eq() 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 @@ -390,7 +383,7 @@ paths: } } expect(status).to eq(200) - expect(response_body).to eq() + expect(response_body).to eq(expected_response) end end From 522a9097bc185a2a59e3ff4aad5bf186c10aca6c Mon Sep 17 00:00:00 2001 From: Chris Drane Date: Tue, 31 Jul 2018 13:39:10 +1000 Subject: [PATCH 5/7] Annotate the Sample App section of the REAMDE to indicated that it uses the :open_api format --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2150c5ec..79d5cbfe 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,7 @@ For both raddocs and apitome, start rails server. Then ## 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 @@ -323,7 +323,9 @@ paths: ## Example of acceptance spec file ```ruby - # spec/acceptance/orders_spec.rb + # spec/acceptance/orders_spec.rb + require 'rails_helper' + require 'rspec_api_documentation/dsl' resource 'Orders' do explanation "Orders resource" From e70edb33db19d8b199facb9b435d1652579e9130 Mon Sep 17 00:00:00 2001 From: Chris Drane Date: Tue, 31 Jul 2018 14:27:41 +1000 Subject: [PATCH 6/7] Upgrade nokogiri to fix security flaw --- Gemfile.lock | 26 +++++++++++++------------- rspec_api_documentation.gemspec | 2 ++ 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/Gemfile.lock b/Gemfile.lock index 73364087..31f46c6b 100644 --- a/Gemfile.lock +++ b/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 diff --git a/rspec_api_documentation.gemspec b/rspec_api_documentation.gemspec index cc975926..ed5edf7d 100644 --- a/rspec_api_documentation.gemspec +++ b/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" From 93e768463aaa347262ba7373dcd51c84d3800daa Mon Sep 17 00:00:00 2001 From: Chris Drane Date: Wed, 1 Aug 2018 09:02:19 +1000 Subject: [PATCH 7/7] Revise README to leave in open_api example spec Put back open_api example spec in same place but labelled it clearly as being open_api specific. Moved generic example of spec up in document. --- README.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 98 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 79d5cbfe..f6b00f65 100644 --- a/README.md +++ b/README.md @@ -85,6 +85,94 @@ For both raddocs and apitome, start rails server. Then 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 ```ruby @@ -319,19 +407,20 @@ paths: description: This description came from configuration file hide: true ``` - -## Example of acceptance spec file - +#### Example of spec file with :open_api format ```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}} @@ -350,11 +439,13 @@ paths: context '200' do example_request 'Getting a list of orders' do expect(status).to eq(200) + expect(response_body).to eq() 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 @@ -385,7 +476,7 @@ paths: } } expect(status).to eq(200) - expect(response_body).to eq(expected_response) + expect(response_body).to eq() end end