feat: allow HAL docs to specify a context so that two relations with the same name in different resources don't clash

Author: bethesque

lib/pact_broker/api/decorators/pact_collection_decorator.rb

@@ -44,6 +44,14 @@ def create_representable_pact pact
             }
           end
         end
+
+        curies do | options |
+          [{
+            name: :pb,
+            href: options[:base_url] + '/doc/{rel}?context=pacts',
+            templated: true
+          }]
+        end
       end
     end
   end

lib/pact_broker/api/decorators/pact_decorator.rb

@@ -160,11 +160,10 @@ def to_hash(options = {})
         curies do | options |
           [{
             name: :pb,
-            href: options[:base_url] + '/doc/{rel}',
+            href: options[:base_url] + '/doc/{rel}?context=pact',
             templated: true
           }]
         end
-
       end
     end
   end

lib/pact_broker/api/decorators/version_decorator.rb

@@ -46,7 +46,7 @@ class VersionDecorator < BaseDecorator
         curies do | options |
           [{
             name: :pb,
-            href: options.fetch(:base_url) + '/doc/{rel}',
+            href: options.fetch(:base_url) + '/doc/{rel}?context=version',
             templated: true
           }]
         end

lib/pact_broker/api/resources/index.rb

@@ -89,7 +89,7 @@ def to_json
               'curies' =>
               [{
                 name: 'pb',
-                href: base_url + '/doc/{rel}',
+                href: base_url + '/doc/{rel}?context=index',
                 templated: true
               }]
             }

lib/pact_broker/doc/controllers/app.rb

@@ -17,24 +17,28 @@ class App < Padrino::Application
         }.freeze
 
         helpers do
-          def view_name_for rel_name
-            MAPPINGS[rel_name] || rel_name
+          def view_name_for rel_name, context = nil
+            view_name = MAPPINGS[rel_name] || rel_name
+            context ? "#{context}/#{view_name}" : view_name
           end
 
-          def resource_exists? rel_name
-            File.exist? File.join(self.class.root, 'views', "#{view_name_for(rel_name)}.markdown")
+          def resource_exists? rel_name, context = nil
+            File.exist? File.join(self.class.root, 'views', "#{view_name_for(rel_name, context)}.markdown")
           end
         end
 
         get ":rel_name" do
           rel_name = params[:rel_name]
-          if resource_exists? rel_name
-            markdown view_name_for(rel_name).to_sym, {:layout_engine => :haml, layout: :'layouts/main'}, {}
+          context = params[:context]
+          view_params = {:layout_engine => :haml, layout: :'layouts/main'}
+          if resource_exists? rel_name, context
+            markdown view_name_for(rel_name, context).to_sym, view_params, {}
+          elsif resource_exists? rel_name
+            markdown view_name_for(rel_name).to_sym, view_params, {}
           else
-            response.status = 404
+            markdown :not_found, view_params, {}
           end
         end
-
       end
     end
   end

lib/pact_broker/doc/views/consumer-version.markdown

@@ -0,0 +1,5 @@
+# Consumer version
+
+Allowed method: `GET`, `PUT`, `DELETE`
+
+The pacticipant (application) version of the consumer that this resource belongs to. Deleting this resource will delete all child resources.

lib/pact_broker/doc/views/latest-pact-versions.markdown lib/pact_broker/doc/views/index/latest-pact-versions.markdown

@@ -0,0 +1 @@
+No documentation exists for this relation yet.

lib/pact_broker/doc/views/latest-provider-pacts-with-tag.markdown lib/pact_broker/doc/views/index/latest-provider-pacts-with-tag.markdown

@@ -1,5 +1,5 @@
 # Diff with previous distinct version
 
-Allowed methods: GET
+Allowed methods: `GET`
 
 This resource displays the difference between the current pact, and the previous "distinct" version. Given that the pact file does not change every time it is published, the previous distinct version is the most recent version published before the current one where the content is actually different.

lib/pact_broker/doc/views/latest-provider-pacts.markdown lib/pact_broker/doc/views/index/latest-provider-pacts.markdown

@@ -0,0 +1,5 @@
+# Diff between two pact versions
+
+Allowed methods: `GET`
+
+This resource displays the difference between the current pact version, and the specified pact version. Note that the pact version in the URL is the pact version content sha, not the consumer version number.

lib/pact_broker/doc/views/latest-tagged-version.markdown lib/pact_broker/doc/views/index/latest-tagged-version.markdown

@@ -1,9 +1,9 @@
 # Publish pact verification result
 
-Allowed methods: POST
+Allowed methods: `POST`
 
 Use a `POST` request to the `pb:publish-verification-results` link (`$['_links']['pb:publish-verification-results']['href']`) in the pact resource to publish the result (either success or failure) of a pact verification. The body of the request must include the success (true or false) and the provider application version that the pact was verified against. It may also include the build URL to facilitate debugging when failures occur.
- 
+
     {
       "success": true,
       "providerApplicationVersion": "4.5.6",

lib/pact_broker/doc/views/latest-version.markdown lib/pact_broker/doc/views/index/latest-version.markdown

@@ -0,0 +1,7 @@
+# Tag Production Version
+
+Allowed methods: `PUT`
+
+Add the "prod" tag to this consumer version. This allows you to retrieve the latest version production version using the following URL.
+
+    http://pact-broker/pacts/provider/{provider}/consumer/{consumer}/latest/prod

lib/pact_broker/doc/views/pacticipants.markdown lib/pact_broker/doc/views/index/pacticipants.markdown

@@ -0,0 +1,5 @@
+# Add Tag to Consumer Version
+
+Allowed methods: `PUT`
+
+Add a tag with the specified name to this consumer version.

lib/pact_broker/doc/views/provider-pacts-with-tag.markdown lib/pact_broker/doc/views/index/provider-pacts-with-tag.markdown

@@ -2,6 +2,6 @@
 
 Allowed methods: GET, PATCH, DELETE
 
-The application that initiates the HTTP request.
+The application that responds to the HTTP request.
 
 See [Pacticipant](/doc/pacticipants) for more information.

lib/pact_broker/doc/views/provider-pacts.markdown lib/pact_broker/doc/views/index/provider-pacts.markdown

@@ -31,19 +31,37 @@ module Controllers
           context "when the resource does not exist" do
             subject { get "/blah" }
 
-            it "returns a 404 status" do
+            it "returns a 200 status, because otherwise, the Rack cascade will make it return a 404 from the webmachine API" do
               subject
-              expect(last_response.status).to eq 404
+              expect(last_response.status).to eq 200
             end
 
             it "returns a html content type" do
               subject
               expect(last_response.headers['Content-Type']).to eq "text/html;charset=utf-8"
             end
 
+            it "returns a custom error page" do
+              subject
+              expect(last_response.body).to include "No documentation exists"
+            end
           end
-        end
 
+          context "when the resource has a context and there is a folder with a matching name" do
+            subject { get "/diff?context=pact" }
+
+            it "returns documentation in a folder of the matching name" do
+              subject
+              expect(last_response.status).to eq 200
+              expect(last_response.body).to include "Diff"
+            end
+
+            it "returns a html content type" do
+              subject
+              expect(last_response.headers['Content-Type']).to eq "text/html;charset=utf-8"
+            end
+          end
+        end
       end
     end
   end

lib/pact_broker/doc/views/publish-pact.markdown lib/pact_broker/doc/views/index/publish-pact.markdown

@@ -21,7 +21,7 @@
     relations_without_docs = {}
 
     relations_that_should_have_docs.each do | relation |
-      path = "/docs/#{relation.split(":", 2).last}"
+      path = "/docs/#{relation.split(":", 2).last}?context=index"
       get path, {}, { 'HTTP_ACCEPT' => 'text/html' }
       if last_response.status != 200
         relations_without_docs[relation] = last_response.status