Update swagger docs with declaration endpoints

spec/requests/api/docs/v1/applications_spec.rb

@@ -45,7 +45,7 @@
       extract_swagger_example(schema: "#/components/schemas/ApplicationResponse", version: :v1)
     end
 
-    it_behaves_like "an API create on resource endpoint documentation",
+    it_behaves_like "an API create on existing resource endpoint documentation",
                     "/api/v1/npq-applications/{id}/accept",
                     "NPQ Applications",
                     "Accept an NPQ application",
@@ -63,7 +63,7 @@
       end
     end
 
-    it_behaves_like "an API create on resource endpoint documentation",
+    it_behaves_like "an API create on existing resource endpoint documentation",
                     "/api/v1/npq-applications/{id}/reject",
                     "NPQ Applications",
                     "Reject an NPQ application",

spec/requests/api/docs/v1/declarations_spec.rb

@@ -5,8 +5,77 @@
   include_context "with authorization for api doc request"
 
   it_behaves_like "an API index Csv endpoint documentation",
-                  "/api/v2/participant-declarations.csv",
+                  "/api/v1/participant-declarations.csv",
                   "Participant declarations",
                   "Participant declarations",
                   "#/components/schemas/DeclarationsCsvResponse"
+
+  it_behaves_like "an API index endpoint documentation",
+                  "/api/v1/participant-declarations",
+                  "Participant declarations",
+                  "Participant declarations",
+                  "#/components/schemas/ListParticipantDeclarationsFilter",
+                  "#/components/schemas/ParticipantDeclarationsResponse"
+
+  describe "single declarations" do
+    let(:lead_provider) { create(:lead_provider) }
+    let(:type) { "participant-declaration" } # check
+    let(:application) { create(:application, :accepted, :with_declaration, lead_provider:) }
+    let(:resource) { application.declarations.first }
+    let(:base_response_example) do
+      extract_swagger_example(schema: "#/components/schemas/ParticipantDeclarationResponse", version: :v1)
+    end
+
+    it_behaves_like "an API show endpoint documentation",
+                    "/api/v1/participant-declarations/{id}",
+                    "Participant declarations",
+                    "Participant declarations",
+                    "#/components/schemas/ParticipantDeclarationResponse"
+
+    it_behaves_like "an API update endpoint documentation",
+                    "/api/v1/participant-declarations/{id}/void",
+                    "Participant declarations",
+                    "Void a declaration",
+                    "The participant declaration being voided",
+                    "#/components/schemas/ParticipantDeclarationResponse" do
+      let(:response_example) do
+        base_response_example.tap do |example|
+          example[:data][:attributes][:state] = "voided"
+          example[:data][:attributes][:voided] = true
+          example[:data][:attributes][:has_passed] = nil
+        end
+      end
+    end
+  end
+
+  describe "create declarations" do
+    let(:lead_provider) { create(:lead_provider) }
+    let(:type) { "participant-declaration" } # check
+    let(:cohort) { create(:cohort, :current) }
+    let(:course_group) { CourseGroup.find_by(name: "leadership") }
+    let(:course) { create(:course, :sl, course_group:) }
+    let!(:schedule) { create(:schedule, :npq_leadership_autumn, course_group:, cohort:) }
+    let(:application) { create(:application, :accepted, cohort:, course:, lead_provider:) }
+    let(:declaration_date) { schedule.applies_from + 1.day }
+    let(:response_example) do
+      extract_swagger_example(schema: "#/components/schemas/ParticipantDeclarationResponse", version: :v1)
+    end
+    let(:invalid_attributes) { { participant_id: "invalid" } }
+    let(:attributes) do
+      {
+        participant_id: application.user.ecf_id,
+        declaration_type: "started",
+        declaration_date: application.schedule.applies_from.rfc3339,
+        course_identifier: course.identifier,
+      }
+    end
+
+    it_behaves_like "an API create on resource endpoint documentation",
+                    "/api/v1/participant-declarations",
+                    "Participant declarations",
+                    "Declare a participant has reached a milestone",
+                    "The participant declaration being created",
+                    "#/components/schemas/ParticipantDeclarationResponse",
+                    "#/components/schemas/ParticipantDeclarationRequest"
+  end
 end

spec/requests/api/docs/v2/applications_spec.rb

@@ -45,7 +45,7 @@
       extract_swagger_example(schema: "#/components/schemas/ApplicationResponse", version: :v2)
     end
 
-    it_behaves_like "an API create on resource endpoint documentation",
+    it_behaves_like "an API create on existing resource endpoint documentation",
                     "/api/v2/npq-applications/{id}/accept",
                     "NPQ Applications",
                     "Accept an NPQ application",
@@ -63,7 +63,7 @@
       end
     end
 
-    it_behaves_like "an API create on resource endpoint documentation",
+    it_behaves_like "an API create on existing resource endpoint documentation",
                     "/api/v2/npq-applications/{id}/reject",
                     "NPQ Applications",
                     "Reject an NPQ application",

spec/requests/api/docs/v2/declarations_spec.rb

@@ -9,4 +9,72 @@
                   "Participant declarations",
                   "Participant declarations",
                   "#/components/schemas/DeclarationsCsvResponse"
+
+  it_behaves_like "an API index endpoint documentation",
+                  "/api/v2/participant-declarations",
+                  "Participant declarations",
+                  "Participant declarations",
+                  "#/components/schemas/ListParticipantDeclarationsFilter",
+                  "#/components/schemas/ParticipantDeclarationsResponse"
+
+  describe "single declarations" do
+    let(:lead_provider) { create(:lead_provider) }
+    let(:type) { "participant-declaration" } # check
+    let(:application) { create(:application, :accepted, :with_declaration, lead_provider:) }
+    let(:resource) { application.declarations.first }
+    let(:base_response_example) do
+      extract_swagger_example(schema: "#/components/schemas/ParticipantDeclarationResponse", version: :v2)
+    end
+
+    it_behaves_like "an API show endpoint documentation",
+                    "/api/v2/participant-declarations/{id}",
+                    "Participant declarations",
+                    "Participant declarations",
+                    "#/components/schemas/ParticipantDeclarationResponse"
+
+    it_behaves_like "an API update endpoint documentation",
+                    "/api/v2/participant-declarations/{id}/void",
+                    "Participant declarations",
+                    "Void a declaration",
+                    "The participant declaration being voided",
+                    "#/components/schemas/ParticipantDeclarationResponse" do
+      let(:response_example) do
+        base_response_example.tap do |example|
+          example[:data][:attributes][:state] = "voided"
+          example[:data][:attributes][:has_passed] = nil
+        end
+      end
+    end
+  end
+
+  describe "create declarations" do
+    let(:lead_provider) { create(:lead_provider) }
+    let(:type) { "participant-declaration" } # check
+    let(:cohort) { create(:cohort, :current) }
+    let(:course_group) { CourseGroup.find_by(name: "leadership") }
+    let(:course) { create(:course, :sl, course_group:) }
+    let!(:schedule) { create(:schedule, :npq_leadership_autumn, course_group:, cohort:) }
+    let(:application) { create(:application, :accepted, cohort:, course:, lead_provider:) }
+    let(:declaration_date) { schedule.applies_from + 1.day }
+    let(:response_example) do
+      extract_swagger_example(schema: "#/components/schemas/ParticipantDeclarationResponse", version: :v2)
+    end
+    let(:invalid_attributes) { { participant_id: "invalid" } }
+    let(:attributes) do
+      {
+        participant_id: application.user.ecf_id,
+        declaration_type: "started",
+        declaration_date: application.schedule.applies_from.rfc3339,
+        course_identifier: course.identifier,
+      }
+    end
+
+    it_behaves_like "an API create on resource endpoint documentation",
+                    "/api/v2/participant-declarations",
+                    "Participant declarations",
+                    "Declare a participant has reached a milestone",
+                    "The participant declaration being created",
+                    "#/components/schemas/ParticipantDeclarationResponse",
+                    "#/components/schemas/ParticipantDeclarationRequest"
+  end
 end

spec/requests/api/docs/v3/applications_spec.rb

@@ -38,7 +38,7 @@
       extract_swagger_example(schema: "#/components/schemas/ApplicationResponse", version: :v3)
     end
 
-    it_behaves_like "an API create on resource endpoint documentation",
+    it_behaves_like "an API create on existing resource endpoint documentation",
                     "/api/v3/npq-applications/{id}/accept",
                     "NPQ Applications",
                     "Accept an NPQ application",
@@ -56,7 +56,7 @@
       end
     end
 
-    it_behaves_like "an API create on resource endpoint documentation",
+    it_behaves_like "an API create on existing resource endpoint documentation",
                     "/api/v3/npq-applications/{id}/reject",
                     "NPQ Applications",
                     "Reject an NPQ application",

spec/requests/api/docs/v3/declarations_spec.rb

@@ -0,0 +1,71 @@
+require "rails_helper"
+require "swagger_helper"
+
+RSpec.describe "Participant Declarations endpoint", type: :request, openapi_spec: "v3/swagger.yaml" do
+  include_context "with authorization for api doc request"
+
+  it_behaves_like "an API index endpoint documentation",
+                  "/api/v3/participant-declarations",
+                  "Participant declarations",
+                  "Participant declarations",
+                  "#/components/schemas/ListParticipantDeclarationsFilter",
+                  "#/components/schemas/ParticipantDeclarationsResponse"
+
+  describe "single declarations" do
+    let(:lead_provider) { create(:lead_provider) }
+    let(:type) { "participant-declaration" } # check
+    let(:application) { create(:application, :accepted, :with_declaration, lead_provider:) }
+    let(:resource) { application.declarations.first }
+    let(:base_response_example) do
+      extract_swagger_example(schema: "#/components/schemas/ParticipantDeclarationResponse", version: :v3)
+    end
+
+    it_behaves_like "an API show endpoint documentation",
+                    "/api/v3/participant-declarations/{id}",
+                    "Participant declarations",
+                    "Participant declarations",
+                    "#/components/schemas/ParticipantDeclarationResponse"
+
+    it_behaves_like "an API update endpoint documentation",
+                    "/api/v3/participant-declarations/{id}/void",
+                    "Participant declarations",
+                    "Void a declaration",
+                    "The participant declaration being voided",
+                    "#/components/schemas/ParticipantDeclarationResponse" do
+      let(:response_example) do
+        base_response_example.tap do |example|
+          example[:data][:attributes][:state] = "voided"
+          example[:data][:attributes][:has_passed] = nil
+        end
+      end
+    end
+  end
+
+  describe "create declarations" do
+    let(:lead_provider) { create(:lead_provider) }
+    let(:type) { "participant-declaration" } # check
+    let(:cohort) { create(:cohort, :current) }
+    let(:course_group) { CourseGroup.find_by(name: "leadership") }
+    let(:course) { create(:course, :sl, course_group:) }
+    let!(:schedule) { create(:schedule, :npq_leadership_autumn, course_group:, cohort:) }
+    let(:application) { create(:application, :accepted, cohort:, course:, lead_provider:) }
+    let(:declaration_date) { schedule.applies_from + 1.day }
+    let(:invalid_attributes) { { participant_id: "invalid" } }
+    let(:attributes) do
+      {
+        participant_id: application.user.ecf_id,
+        declaration_type: "started",
+        declaration_date: application.schedule.applies_from.rfc3339,
+        course_identifier: course.identifier,
+      }
+    end
+
+    it_behaves_like "an API create on resource endpoint documentation",
+                    "/api/v3/participant-declarations",
+                    "Participant declarations",
+                    "Declare a participant has reached a milestone",
+                    "The participant declaration being created",
+                    "#/components/schemas/ParticipantDeclarationResponse",
+                    "#/components/schemas/ParticipantDeclarationRequest"
+  end
+end

spec/support/shared_examples/api_create_on_existing_resource_endpoint_documentation_support.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+RSpec.shared_examples "an API create on existing resource endpoint documentation" do |url, tag, resource_description, response_description, response_schema_ref, request_schema_ref|
+  path url do
+    post resource_description do
+      tags tag
+      consumes "application/json"
+      produces "application/json"
+      security [api_key: []]
+
+      parameter name: :id,
+                in: :path,
+                required: true,
+                schema: {
+                  "$ref": "#/components/schemas/IDAttribute",
+                }
+
+      if request_schema_ref
+        parameter name: :params,
+                  in: :body,
+                  style: :deepObject,
+                  required: false,
+                  schema: {
+                    "$ref": request_schema_ref,
+                  }
+
+        let(:params) do
+          {
+            data: {
+              type:,
+              attributes:,
+            },
+          }
+        end
+      end
+
+      response "200", response_description do
+        let(:id) { resource.ecf_id }
+
+        schema({ "$ref": response_schema_ref })
+
+        after do |example|
+          if defined?(response_example)
+            example_spec = {
+              "application/json" => {
+                examples: {
+                  success: {
+                    value: response_example,
+                  },
+                },
+              },
+            }
+            example.metadata[:response][:content] = example_spec
+          end
+        end
+
+        run_test!
+      end
+
+      response "401", "Unauthorized" do
+        let(:id) { resource.ecf_id }
+        let(:token) { "invalid" }
+
+        schema({ "$ref": "#/components/schemas/UnauthorisedResponse" })
+
+        run_test!
+      end
+
+      if request_schema_ref
+        response "400", "Bad request" do
+          let(:id) { resource.ecf_id }
+          let(:params) { { data: {} } }
+
+          schema({ "$ref": "#/components/schemas/BadRequestResponse" })
+
+          run_test!
+        end
+
+        response "422", "Unprocessable entity" do
+          let(:id) { resource.ecf_id }
+          let(:attributes) { invalid_attributes }
+
+          schema({ "$ref": "#/components/schemas/UnprocessableEntityResponse" })
+
+          run_test!
+        end
+      end
+
+      response "404", "Not found", exceptions_app: true do
+        let(:id) { SecureRandom.uuid }
+
+        schema({ "$ref": "#/components/schemas/NotFoundResponse" })
+
+        run_test!
+      end
+    end
+  end
+end