From 6534f285819c3741db5f7c46a5881bfdd97a8323 Mon Sep 17 00:00:00 2001 From: Steven Vandevelde Date: Wed, 14 Feb 2018 16:47:35 +0100 Subject: [PATCH 01/17] Add api_explanation to the api-blueprint template --- templates/rspec_api_documentation/api_blueprint_index.mustache | 3 +++ 1 file changed, 3 insertions(+) diff --git a/templates/rspec_api_documentation/api_blueprint_index.mustache b/templates/rspec_api_documentation/api_blueprint_index.mustache index 865f24a3..880eab4c 100644 --- a/templates/rspec_api_documentation/api_blueprint_index.mustache +++ b/templates/rspec_api_documentation/api_blueprint_index.mustache @@ -1,5 +1,8 @@ FORMAT: 1A + # {{ api_name }} +{{{ api_explanation }}} + {{# sections }} # Group {{ resource_name }} From 4a30554ae81fca69de35eb83857e9bb9b1a0466d Mon Sep 17 00:00:00 2001 From: Steven Vandevelde Date: Wed, 14 Feb 2018 18:33:07 +0100 Subject: [PATCH 02/17] Add route and method explanations --- lib/rspec_api_documentation/dsl/resource.rb | 8 +++++++- lib/rspec_api_documentation/views/api_blueprint_index.rb | 2 ++ .../rspec_api_documentation/api_blueprint_index.mustache | 2 +- 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/lib/rspec_api_documentation/dsl/resource.rb b/lib/rspec_api_documentation/dsl/resource.rb index 1e45d4e2..5d1e35e0 100644 --- a/lib/rspec_api_documentation/dsl/resource.rb +++ b/lib/rspec_api_documentation/dsl/resource.rb @@ -71,7 +71,13 @@ def header(name, value) end def explanation(text) - safe_metadata(:resource_explanation, text) + if metadata[:method].present? + safe_metadata(:method_explanation, text) + elsif metadata[:route_uri].present? + safe_metadata(:route_explanation, text) + else + safe_metadata(:resource_explanation, text) + end end private diff --git a/lib/rspec_api_documentation/views/api_blueprint_index.rb b/lib/rspec_api_documentation/views/api_blueprint_index.rb index 75e19449..d98053dc 100644 --- a/lib/rspec_api_documentation/views/api_blueprint_index.rb +++ b/lib/rspec_api_documentation/views/api_blueprint_index.rb @@ -16,6 +16,7 @@ def sections { http_method: http_method, description: examples.first.respond_to?(:action_name) && examples.first.action_name, + explanation: examples.first.respond_to?(:method_explanation) && examples.first.method_explanation, examples: examples } end @@ -25,6 +26,7 @@ def sections "has_parameters?".to_sym => params.size > 0, route: format_route(examples[0]), route_name: examples[0][:route_name], + explanation: examples[0][:route_explanation], attributes: attrs, parameters: params, http_methods: methods diff --git a/templates/rspec_api_documentation/api_blueprint_index.mustache b/templates/rspec_api_documentation/api_blueprint_index.mustache index 880eab4c..cb797bdd 100644 --- a/templates/rspec_api_documentation/api_blueprint_index.mustache +++ b/templates/rspec_api_documentation/api_blueprint_index.mustache @@ -22,8 +22,8 @@ FORMAT: 1A description: {{ description }} {{/ description }} {{# explanation }} +{{{ explanation }}} -explanation: {{ explanation }} {{/ explanation }} {{# has_parameters? }} From 56873e70427ae2c700a3a2a58fced69e3933c14d Mon Sep 17 00:00:00 2001 From: Steven Vandevelde Date: Wed, 14 Feb 2018 18:37:42 +0100 Subject: [PATCH 03/17] Add explanations to template --- .../rspec_api_documentation/api_blueprint_index.mustache | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/templates/rspec_api_documentation/api_blueprint_index.mustache b/templates/rspec_api_documentation/api_blueprint_index.mustache index cb797bdd..5ad16811 100644 --- a/templates/rspec_api_documentation/api_blueprint_index.mustache +++ b/templates/rspec_api_documentation/api_blueprint_index.mustache @@ -42,11 +42,20 @@ description: {{ description }} {{# http_methods }} ### {{ description }} [{{ http_method }}] + +{{# explanation }} +{{{ explanation }}} +{{/ explanation }} + {{# examples }} {{# requests }} {{# has_request? }} + Request {{ description }}{{# request_content_type }} ({{ request_content_type }}){{/ request_content_type }} + + {{# explanation }} + {{{ explanation }}} + {{/ explanation }} {{/ has_request? }} {{# request_headers_text }} From b9d78017327ec98d25838df8c019fd547aaa4d8e Mon Sep 17 00:00:00 2001 From: Steven Vandevelde Date: Wed, 14 Feb 2018 18:50:19 +0100 Subject: [PATCH 04/17] Fix attributes --- .../api_blueprint_index.mustache | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/templates/rspec_api_documentation/api_blueprint_index.mustache b/templates/rspec_api_documentation/api_blueprint_index.mustache index 5ad16811..20ecb01e 100644 --- a/templates/rspec_api_documentation/api_blueprint_index.mustache +++ b/templates/rspec_api_documentation/api_blueprint_index.mustache @@ -28,22 +28,24 @@ description: {{ description }} {{# has_parameters? }} + Parameters + {{# parameters }} - + {{ name }}{{# example }}: {{ example }}{{/ example }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }} + + {{ name }}{{# example }}: {{ example }}{{/ example }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }} {{/ parameters }} {{/ has_parameters? }} +{{# http_methods }} + +### {{ description }} [{{ http_method }}] {{# has_attributes? }} -+ Attributes (object) ++ Parameters + {{# attributes }} - + {{ name }}{{# example }}: {{ example }}{{/ example }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }} + + {{ name }}{{# example }}: {{ example }}{{/ example }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }} {{/ attributes }} {{/ has_attributes? }} -{{# http_methods }} - -### {{ description }} [{{ http_method }}] - {{# explanation }} + {{{ explanation }}} {{/ explanation }} From bb5546de35b55cd4ea1f67bc71d4a7be71dd2852 Mon Sep 17 00:00:00 2001 From: Steven Vandevelde Date: Wed, 14 Feb 2018 18:57:13 +0100 Subject: [PATCH 05/17] Further improve template --- .../rspec_api_documentation/api_blueprint_index.mustache | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/templates/rspec_api_documentation/api_blueprint_index.mustache b/templates/rspec_api_documentation/api_blueprint_index.mustache index 20ecb01e..c3acad32 100644 --- a/templates/rspec_api_documentation/api_blueprint_index.mustache +++ b/templates/rspec_api_documentation/api_blueprint_index.mustache @@ -19,11 +19,11 @@ FORMAT: 1A ## {{ route_name }} [{{ route }}] {{# description }} -description: {{ description }} +{{ description }} {{/ description }} {{# explanation }} -{{{ explanation }}} +{{{ explanation }}} {{/ explanation }} {{# has_parameters? }} @@ -36,6 +36,10 @@ description: {{ description }} {{# http_methods }} ### {{ description }} [{{ http_method }}] +{{# explanation }} + +{{{ explanation }}} +{{/ explanation }} {{# has_attributes? }} + Parameters From d7d85ef022a3926a383bac1991bdeb02778d8ce9 Mon Sep 17 00:00:00 2001 From: Steven Vandevelde Date: Wed, 14 Feb 2018 20:34:00 +0100 Subject: [PATCH 06/17] Improve field properties --- lib/rspec_api_documentation/views/api_blueprint_index.rb | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/lib/rspec_api_documentation/views/api_blueprint_index.rb b/lib/rspec_api_documentation/views/api_blueprint_index.rb index d98053dc..ddc0f8a0 100644 --- a/lib/rspec_api_documentation/views/api_blueprint_index.rb +++ b/lib/rspec_api_documentation/views/api_blueprint_index.rb @@ -66,7 +66,7 @@ def format_route(example) # type: "string", # name: "id", # description: "The id", - # properties_description: "required, string" + # properties_description: "string, required" # } def fields(property_name, examples) examples @@ -76,8 +76,10 @@ def fields(property_name, examples) .uniq { |property| property[:name] } .map do |property| properties = [] - properties << "required" if property[:required] properties << property[:type] if property[:type] + properties << "required" if property[:required] == true + properties << "optional" if property[:required].blank? + if properties.count > 0 property[:properties_description] = properties.join(", ") else From 8048cd27a21ef882a599d1305748e1213e0f1ac6 Mon Sep 17 00:00:00 2001 From: Steven Vandevelde Date: Wed, 14 Feb 2018 21:46:18 +0100 Subject: [PATCH 07/17] Clean up template --- .../rspec_api_documentation/api_blueprint_index.mustache | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/templates/rspec_api_documentation/api_blueprint_index.mustache b/templates/rspec_api_documentation/api_blueprint_index.mustache index c3acad32..baa955d7 100644 --- a/templates/rspec_api_documentation/api_blueprint_index.mustache +++ b/templates/rspec_api_documentation/api_blueprint_index.mustache @@ -30,7 +30,7 @@ FORMAT: 1A + Parameters {{# parameters }} - + {{ name }}{{# example }}: {{ example }}{{/ example }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }} + + {{ name }}{{# example }}: {{{ example }}}{{/ example }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }} {{/ parameters }} {{/ has_parameters? }} {{# http_methods }} @@ -45,13 +45,9 @@ FORMAT: 1A + Parameters {{# attributes }} - + {{ name }}{{# example }}: {{ example }}{{/ example }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }} + + {{ name }}{{# example }}: {{{ example }}}{{/ example }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }} {{/ attributes }} {{/ has_attributes? }} -{{# explanation }} - -{{{ explanation }}} -{{/ explanation }} {{# examples }} {{# requests }} From 4758f6c2604c70b0aa53207a99977a0f9dca8c19 Mon Sep 17 00:00:00 2001 From: Steven Vandevelde Date: Thu, 15 Feb 2018 11:55:29 +0100 Subject: [PATCH 08/17] Fix specs --- .gitignore | 1 + Gemfile.lock | 6 +++--- lib/rspec_api_documentation/dsl/resource.rb | 2 +- .../views/api_blueprint_index.rb | 4 ++-- rspec_api_documentation.gemspec | 2 +- spec/http_test_client_spec.rb | 6 +++--- spec/views/api_blueprint_index_spec.rb | 13 +++++++++---- 7 files changed, 20 insertions(+), 14 deletions(-) diff --git a/.gitignore b/.gitignore index a0190963..473211c6 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +doc tmp .rvmrc .ruby-version diff --git a/Gemfile.lock b/Gemfile.lock index 73364087..8f0f6944 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -57,7 +57,7 @@ GEM multipart-post (>= 1.2, < 3) ffi (1.9.10) gherkin (3.2.0) - hashdiff (0.2.3) + hashdiff (0.3.7) httpclient (2.7.1) i18n (0.7.0) inch (0.7.0) @@ -129,7 +129,7 @@ GEM tins (1.8.2) tzinfo (1.2.2) thread_safe (~> 0.1) - webmock (1.22.6) + webmock (3.3.0) addressable (>= 2.3.6) crack (>= 0.3.2) hashdiff @@ -154,7 +154,7 @@ DEPENDENCIES rspec_api_documentation! sinatra (~> 1.4, >= 1.4.4) thin (~> 1.6, >= 1.6.3) - webmock (~> 1.7) + webmock (~> 3.3) BUNDLED WITH 1.16.1 diff --git a/lib/rspec_api_documentation/dsl/resource.rb b/lib/rspec_api_documentation/dsl/resource.rb index 5d1e35e0..60b45735 100644 --- a/lib/rspec_api_documentation/dsl/resource.rb +++ b/lib/rspec_api_documentation/dsl/resource.rb @@ -30,7 +30,7 @@ def self.define_action(method) def callback(*args, &block) begin - require 'webmock' + require 'webmock/rspec' rescue LoadError raise "Callbacks require webmock to be installed" end diff --git a/lib/rspec_api_documentation/views/api_blueprint_index.rb b/lib/rspec_api_documentation/views/api_blueprint_index.rb index ddc0f8a0..4fbb2b6f 100644 --- a/lib/rspec_api_documentation/views/api_blueprint_index.rb +++ b/lib/rspec_api_documentation/views/api_blueprint_index.rb @@ -15,8 +15,8 @@ def sections methods = examples.group_by(&:http_method).map do |http_method, examples| { http_method: http_method, - description: examples.first.respond_to?(:action_name) && examples.first.action_name, - explanation: examples.first.respond_to?(:method_explanation) && examples.first.method_explanation, + description: examples.first.try(:action_name), + explanation: examples.first.try(:[], :metadata).try(:[], :method_explanation), examples: examples } end diff --git a/rspec_api_documentation.gemspec b/rspec_api_documentation.gemspec index cc975926..8e1ba9ac 100644 --- a/rspec_api_documentation.gemspec +++ b/rspec_api_documentation.gemspec @@ -26,7 +26,7 @@ Gem::Specification.new do |s| s.add_development_dependency "rake", "~> 10.1" s.add_development_dependency "rack-test", "~> 0.6.2" s.add_development_dependency "rack-oauth2", "~> 1.2.2", ">= 1.0.7" - s.add_development_dependency "webmock", "~> 1.7" + s.add_development_dependency "webmock", "~> 3.3" 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" diff --git a/spec/http_test_client_spec.rb b/spec/http_test_client_spec.rb index e2282371..9f73bb78 100644 --- a/spec/http_test_client_spec.rb +++ b/spec/http_test_client_spec.rb @@ -3,7 +3,7 @@ require 'capybara' require 'capybara/server' require 'sinatra/base' -require 'webmock' +require 'webmock/rspec' require 'support/stub_app' describe RspecApiDocumentation::HttpTestClient do @@ -16,7 +16,7 @@ Rack::Handler::Thin.run(app, :Port => port) end - server = Capybara::Server.new(StubApp.new, 8888) + server = Capybara::Server.new(StubApp.new, 29876) server.boot end @@ -25,7 +25,7 @@ end let(:client_context) { |example| double(example: example, app_root: 'nowhere') } - let(:target_host) { 'http://localhost:8888' } + let(:target_host) { 'http://localhost:29876' } let(:test_client) { RspecApiDocumentation::HttpTestClient.new(client_context, {host: target_host}) } subject { test_client } diff --git a/spec/views/api_blueprint_index_spec.rb b/spec/views/api_blueprint_index_spec.rb index 862016c2..039a4833 100644 --- a/spec/views/api_blueprint_index_spec.rb +++ b/spec/views/api_blueprint_index_spec.rb @@ -63,7 +63,10 @@ let(:rspec_example_comments) do comment_group.route "/comments", "Comments Collection" do + explanation "Route explanation" + get("/comments") do + explanation "Method explanation" example_request 'Get all comments' do end end @@ -98,6 +101,8 @@ post_route = sections[1][:routes][1] post_route_with_optionals = sections[1][:routes][2] + expect(comments_route[:explanation]).to eq "Route explanation" + comments_examples = comments_route[:http_methods].map { |http_method| http_method[:examples] }.flatten expect(comments_examples.size).to eq 1 expect(comments_route[:route]).to eq "/comments" @@ -118,7 +123,7 @@ example: "1", name: "id", description: "The id", - properties_description: "required, string" + properties_description: "string, required" }] expect(post_route[:has_attributes?]).to eq true expect(post_route[:attributes]).to eq [{ @@ -139,11 +144,11 @@ example: "1", name: "id", description: "The id", - properties_description: "required, string" + properties_description: "string, required" }, { name: "option", description: nil, - properties_description: nil + properties_description: "optional" }] expect(post_route_with_optionals[:has_attributes?]).to eq false expect(post_route_with_optionals[:attributes]).to eq [] @@ -159,7 +164,7 @@ required: false, name: "description", description: nil, - properties_description: nil + properties_description: "optional" }] end end From 35c6a8bd35e94da61fc45dc6351dd276b1f3824c Mon Sep 17 00:00:00 2001 From: Steven Vandevelde Date: Thu, 15 Feb 2018 15:01:54 +0100 Subject: [PATCH 09/17] Actually use the attributes in the request --- .../dsl/endpoint/params.rb | 16 ++++++++++++---- spec/dsl_spec.rb | 7 +++++++ 2 files changed, 19 insertions(+), 4 deletions(-) diff --git a/lib/rspec_api_documentation/dsl/endpoint/params.rb b/lib/rspec_api_documentation/dsl/endpoint/params.rb index 037788b8..c2501b20 100644 --- a/lib/rspec_api_documentation/dsl/endpoint/params.rb +++ b/lib/rspec_api_documentation/dsl/endpoint/params.rb @@ -13,11 +13,19 @@ def initialize(example_group, example, extra_params) end def call - parameters = example.metadata.fetch(:parameters, {}).inject({}) do |hash, param| + set_param = -> hash, param { SetParam.new(self, hash, param).call - end - parameters.deep_merge!(extra_params) - parameters + } + + example.metadata + .fetch(:parameters, {}) + .inject({}, &set_param) + .deep_merge( + example.metadata + .fetch(:attributes, {}) + .inject({}, &set_param) + ) + .deep_merge(extra_params) end private diff --git a/spec/dsl_spec.rb b/spec/dsl_spec.rb index 94253414..cd841aad 100644 --- a/spec/dsl_spec.rb +++ b/spec/dsl_spec.rb @@ -130,9 +130,12 @@ parameter :id, 'The ID of the resource.', :required => true, scope: :data parameter :note, "Any additional notes about your order." + attribute :tip, "The amount you want to tip", :required => true + let(:type) { "coffee" } let(:size) { "medium" } let(:data_id) { 2 } + let(:tip) { 20 } let(:id) { 1 } @@ -157,6 +160,10 @@ expect(params['data']).to eq({'id' => 2}) end + it "should set attributes as well" do + expect(params["tip"]).to eq(tip()) + end + it "should allow extra parameters to be passed in" do expect(client).to receive(method).with(path, params.merge("extra" => true), nil) do_request(:extra => true) From 24ff4f79950174264bd03e15f3e85ec3add83e5a Mon Sep 17 00:00:00 2001 From: Steven Vandevelde Date: Thu, 15 Feb 2018 15:25:19 +0100 Subject: [PATCH 10/17] Handle multiple examples correctly --- .../rspec_api_documentation/api_blueprint_index.mustache | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/templates/rspec_api_documentation/api_blueprint_index.mustache b/templates/rspec_api_documentation/api_blueprint_index.mustache index baa955d7..57e4885b 100644 --- a/templates/rspec_api_documentation/api_blueprint_index.mustache +++ b/templates/rspec_api_documentation/api_blueprint_index.mustache @@ -35,7 +35,9 @@ FORMAT: 1A {{/ has_parameters? }} {{# http_methods }} -### {{ description }} [{{ http_method }}] +{{# examples }} + +### {{ action_name }} [{{ http_method }}] {{# explanation }} {{{ explanation }}} @@ -49,7 +51,6 @@ FORMAT: 1A {{/ attributes }} {{/ has_attributes? }} -{{# examples }} {{# requests }} {{# has_request? }} From f221b66cf5905f6136f9e12d2d48d00e522a4818 Mon Sep 17 00:00:00 2001 From: Steven Vandevelde Date: Thu, 15 Feb 2018 15:52:23 +0100 Subject: [PATCH 11/17] Remove example from parameters and attributes --- lib/rspec_api_documentation/views/api_blueprint_index.rb | 1 - .../rspec_api_documentation/api_blueprint_index.mustache | 7 +++---- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/lib/rspec_api_documentation/views/api_blueprint_index.rb b/lib/rspec_api_documentation/views/api_blueprint_index.rb index 4fbb2b6f..e87684dd 100644 --- a/lib/rspec_api_documentation/views/api_blueprint_index.rb +++ b/lib/rspec_api_documentation/views/api_blueprint_index.rb @@ -62,7 +62,6 @@ def format_route(example) # with all of its properties, like name, description, required. # { # required: true, - # example: "1", # type: "string", # name: "id", # description: "The id", diff --git a/templates/rspec_api_documentation/api_blueprint_index.mustache b/templates/rspec_api_documentation/api_blueprint_index.mustache index 57e4885b..d866ab73 100644 --- a/templates/rspec_api_documentation/api_blueprint_index.mustache +++ b/templates/rspec_api_documentation/api_blueprint_index.mustache @@ -30,12 +30,13 @@ FORMAT: 1A + Parameters {{# parameters }} - + {{ name }}{{# example }}: {{{ example }}}{{/ example }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }} + + {{ name }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }} {{/ parameters }} {{/ has_parameters? }} {{# http_methods }} {{# examples }} +{{# requests }} ### {{ action_name }} [{{ http_method }}] {{# explanation }} @@ -47,11 +48,9 @@ FORMAT: 1A + Parameters {{# attributes }} - + {{ name }}{{# example }}: {{{ example }}}{{/ example }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }} + + {{ name }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }} {{/ attributes }} {{/ has_attributes? }} - -{{# requests }} {{# has_request? }} + Request {{ description }}{{# request_content_type }} ({{ request_content_type }}){{/ request_content_type }} From 3429130e030477660924c0ce1e41a1196d27c45f Mon Sep 17 00:00:00 2001 From: Steven Vandevelde Date: Thu, 15 Feb 2018 16:00:33 +0100 Subject: [PATCH 12/17] Add ability to define default values for parameters and attributes --- .../rspec_api_documentation/api_blueprint_index.mustache | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/templates/rspec_api_documentation/api_blueprint_index.mustache b/templates/rspec_api_documentation/api_blueprint_index.mustache index d866ab73..a176f56c 100644 --- a/templates/rspec_api_documentation/api_blueprint_index.mustache +++ b/templates/rspec_api_documentation/api_blueprint_index.mustache @@ -48,7 +48,11 @@ FORMAT: 1A + Parameters {{# attributes }} - + {{ name }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }} + + {{ name }}{{# value }}: {{ value }}{{/ value }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }} +{{# default }} + + + Default: {{ default }} +{{/ default }} {{/ attributes }} {{/ has_attributes? }} {{# has_request? }} From 4f8c44df6f8e07eaf47688c42fe28da09b411028 Mon Sep 17 00:00:00 2001 From: Steven Vandevelde Date: Fri, 16 Feb 2018 16:08:14 +0100 Subject: [PATCH 13/17] Move method explanation to the right place in the template --- .../rspec_api_documentation/api_blueprint_index.mustache | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/templates/rspec_api_documentation/api_blueprint_index.mustache b/templates/rspec_api_documentation/api_blueprint_index.mustache index a176f56c..f099b1be 100644 --- a/templates/rspec_api_documentation/api_blueprint_index.mustache +++ b/templates/rspec_api_documentation/api_blueprint_index.mustache @@ -35,14 +35,14 @@ FORMAT: 1A {{/ has_parameters? }} {{# http_methods }} -{{# examples }} -{{# requests }} - -### {{ action_name }} [{{ http_method }}] +### {{ description }} [{{ http_method }}] {{# explanation }} {{{ explanation }}} {{/ explanation }} + +{{# examples }} +{{# requests }} {{# has_attributes? }} + Parameters From ec9898118b05ea42b8e36b6b804c014407dff4ca Mon Sep 17 00:00:00 2001 From: Steven Vandevelde Date: Mon, 19 Feb 2018 17:17:55 +0100 Subject: [PATCH 14/17] Allow the use of action methods (eg. `get`) outside `route` blocks --- lib/rspec_api_documentation/dsl/resource.rb | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/lib/rspec_api_documentation/dsl/resource.rb b/lib/rspec_api_documentation/dsl/resource.rb index 60b45735..c6569e2e 100644 --- a/lib/rspec_api_documentation/dsl/resource.rb +++ b/lib/rspec_api_documentation/dsl/resource.rb @@ -8,15 +8,25 @@ def self.define_action(method) define_method method do |*args, &block| options = args.extract_options! options[:method] = method + if metadata[:route_uri] options[:route] = metadata[:route_uri] options[:action_name] = args.first + else options[:route] = args.first + options[:route_uri] = args[0].gsub(/\{.*\}/, "") + options[:route_optionals] = (optionals = args[0].match(/(\{.*\})/) and optionals[-1]) + options[:route_name] = options[:route_name] || options[:route] + options[:action_name] = options[:action_name] || method.to_s.upcase + end + options[:api_doc_dsl] = :endpoint + args.push(options) args[0] = "#{method.to_s.upcase} #{args[0]}" + context(*args, &block) end end From 13ea7ded78e7c9ef6c840034ec166ebd8645ad28 Mon Sep 17 00:00:00 2001 From: Steven Vandevelde Date: Wed, 21 Feb 2018 19:51:35 +0100 Subject: [PATCH 15/17] Allow multiple http methods if they have different action names --- .../views/api_blueprint_index.rb | 20 +++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/lib/rspec_api_documentation/views/api_blueprint_index.rb b/lib/rspec_api_documentation/views/api_blueprint_index.rb index e87684dd..b8fe44a1 100644 --- a/lib/rspec_api_documentation/views/api_blueprint_index.rb +++ b/lib/rspec_api_documentation/views/api_blueprint_index.rb @@ -12,14 +12,18 @@ def sections attrs = fields(:attributes, examples) params = fields(:parameters, examples) - methods = examples.group_by(&:http_method).map do |http_method, examples| - { - http_method: http_method, - description: examples.first.try(:action_name), - explanation: examples.first.try(:[], :metadata).try(:[], :method_explanation), - examples: examples - } - end + methods = examples + .group_by { |e| "#{e.http_method} - #{e.action_name}" } + .map do |group, examples| + first_example = examples.first + + { + http_method: first_example.try(:http_method), + description: first_example.try(:action_name), + explanation: first_example.try(:[], :metadata).try(:[], :method_explanation), + examples: examples + } + end { "has_attributes?".to_sym => attrs.size > 0, From 454d0ab5c610f61f9d1c95de9855d4477a426cbc Mon Sep 17 00:00:00 2001 From: Steven Vandevelde Date: Tue, 27 Feb 2018 23:13:14 +0100 Subject: [PATCH 16/17] Move the description of the parameters --- .../api_blueprint_index.mustache | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/templates/rspec_api_documentation/api_blueprint_index.mustache b/templates/rspec_api_documentation/api_blueprint_index.mustache index f099b1be..cbdae894 100644 --- a/templates/rspec_api_documentation/api_blueprint_index.mustache +++ b/templates/rspec_api_documentation/api_blueprint_index.mustache @@ -30,7 +30,11 @@ FORMAT: 1A + Parameters {{# parameters }} - + {{ name }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }} + + {{ name }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }} +{{# description }} + + {{ description }} +{{/ description }} {{/ parameters }} {{/ has_parameters? }} {{# http_methods }} @@ -48,7 +52,11 @@ FORMAT: 1A + Parameters {{# attributes }} - + {{ name }}{{# value }}: {{ value }}{{/ value }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }} + + {{ name }}{{# value }}: {{ value }}{{/ value }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }} +{{# description }} + + {{ description }} +{{/ description }} {{# default }} + Default: {{ default }} From b2ec981e1a8de98011044c415df7fc5a184fb03e Mon Sep 17 00:00:00 2001 From: Steven Vandevelde Date: Wed, 28 Feb 2018 14:53:19 +0100 Subject: [PATCH 17/17] Add ability to sort the routes alphabetically --- lib/rspec_api_documentation/configuration.rb | 3 +++ lib/rspec_api_documentation/views/api_blueprint_index.rb | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/lib/rspec_api_documentation/configuration.rb b/lib/rspec_api_documentation/configuration.rb index c4721674..24845653 100644 --- a/lib/rspec_api_documentation/configuration.rb +++ b/lib/rspec_api_documentation/configuration.rb @@ -81,6 +81,9 @@ def self.add_setting(name, opts = {}) add_setting :response_headers_to_include, :default => nil add_setting :html_embedded_css_file, :default => nil + # sorting + add_setting :sort_routes, :default => false + # renamed to request_body_formatter. here for backwards compatibility add_setting :post_body_formatter, :default => nil diff --git a/lib/rspec_api_documentation/views/api_blueprint_index.rb b/lib/rspec_api_documentation/views/api_blueprint_index.rb index b8fe44a1..57edaba1 100644 --- a/lib/rspec_api_documentation/views/api_blueprint_index.rb +++ b/lib/rspec_api_documentation/views/api_blueprint_index.rb @@ -38,7 +38,7 @@ def sections end section.merge({ - routes: routes + routes: @configuration.sort_routes ? routes.sort_by { |r| r[:route_name] } : routes }) end end