feat: add missing HAL docs for various relations and correct test that should have identified their absence

Author: bethesque

lib/pact_broker/doc/views/can-i-deploy.markdown

@@ -0,0 +1,14 @@
+# Can I Deploy
+
+Allowed methods: `GET`
+
+A simplified resource that accepts the same parameters as the basic usage of the `can-i-deploy` CLI command.
+
+**Parameters**:
+
+* _pacticipant_: The name of the pacticipant (application) you want to deploy (required).
+* _version_: The version of the pacticipant (application) you want to deploy (required).
+* _to_: The tag used to identify the environment into which you wish to deploy the application (eg. `test` or `prod`). This assumes you have already tagged the currently deployed versions of each of the integrated applications with the same tag. To be specific, the logic checks if the application version you have specified is compatible with the latest versions _for the specified tag_ of all the other applications it is integrated with. This parameter is optional - if not specified, it checks for compatiblity with the latest version of all the integrated applications.
+
+
+If you have an environment that you identify with the tag `prod`, and each time you deployed an application to the prod environment you tagged the relevant application version in the Pact Broker with the tag `prod`, then calling `/can-i-deploy?pacticipant=Foo&version=734137278d&to=prod` will check that version 734137278d of Foo has a successful verification result with each of the integrated application versions that are currently in prod. That is, it is safe to deploy.

lib/pact_broker/doc/views/index/pacticipant-version-tag.markdown

@@ -0,0 +1,8 @@
+# Pacticipant version tag
+
+Allowed methods: `GET`, `PUT`, `DELETE`
+Path: `/pacticipants/{pacticipant}/versions/{version}/tags/{tag}`
+
+To create a tag, send an empty request with the URL specified above and `Content-Type` of `application/json`.
+
+Tags must be applied before pacts or verification results are published to ensure that the webhook fires with the correct metadata.

lib/pact_broker/doc/views/matrix.markdown

@@ -0,0 +1,7 @@
+# Matrix
+
+Allowed methods: `GET`
+
+This resource returns the "cartesian join" of every pact publication and every verification results publication, and is used to determine whether or not an application is safe to deploy.
+
+If you need to use this API, consider calling the `/can-i-deploy` resource instead.

lib/pact_broker/doc/views/metrics.markdown

@@ -0,0 +1,5 @@
+# Metrics
+
+Allowed methods: `GET`
+
+Returns counts for the Pact Broker resources.

spec/lib/pact_broker/doc/coverage_spec.rb

@@ -15,15 +15,21 @@
 
   let(:index_response) { get "/", {}, { 'HTTP_ACCEPT' => 'application/hal+json' } }
   let(:index_body) { JSON.parse(index_response.body) }
+  let(:docs_missing_string) { "No documentation exists"}
+
+  it "returns a known message when the documentation doesn't exist" do
+    get "/docs/does-not-exist?context=index", {}, { 'HTTP_ACCEPT' => 'text/html' }
+    expect(last_response.body).to include docs_missing_string
+  end
 
   it "has a document for each relation" do
-    relations_that_should_have_docs = index_body['_links'].keys - ['self', 'curies']
+    relations_that_should_have_docs = index_body['_links'].keys - ['self', 'curies', 'beta:provider-pacts-for-verification']
     relations_without_docs = {}
 
     relations_that_should_have_docs.each do | relation |
       path = "/docs/#{relation.split(":", 2).last}?context=index"
       get path, {}, { 'HTTP_ACCEPT' => 'text/html' }
-      if last_response.status != 200
+      if last_response.body.include?(docs_missing_string)
         relations_without_docs[relation] = last_response.status
       end
     end