From 9ee1113e092ec2e4fd3b559feb1a06a63900c24f Mon Sep 17 00:00:00 2001 From: Pablo M Date: Sat, 29 Jun 2024 13:53:29 +0100 Subject: [PATCH 01/11] Add Swagger support for V1 declarations --- public/api/docs/v3/swagger.yaml | 433 +++++++++++++++ .../requests/api/docs/v1/applications_spec.rb | 4 +- .../requests/api/docs/v1/declarations_spec.rb | 58 ++ .../requests/api/docs/v2/applications_spec.rb | 4 +- .../requests/api/docs/v3/applications_spec.rb | 4 +- .../requests/api/docs/v3/declarations_spec.rb | 6 + ...resource_endpoint_documentation_support.rb | 98 ++++ ...resource_endpoint_documentation_support.rb | 20 - ...i_update_endpoint_documentation_support.rb | 56 +- spec/swagger_helper.rb | 9 + .../filters/list_participant_declarations.rb | 21 + .../models/participant_declaration.rb | 505 ++++++++++++++++++ ...rticipant_declaration_completed_request.rb | 66 +++ .../participant_declaration_request.rb | 20 + ...articipant_declaration_retained_request.rb | 59 ++ ...participant_declaration_started_request.rb | 58 ++ .../responses/participant_declaration.rb | 15 + .../responses/participant_declarations.rb | 16 + 18 files changed, 1400 insertions(+), 52 deletions(-) create mode 100644 spec/requests/api/docs/v3/declarations_spec.rb create mode 100644 spec/support/shared_examples/api_create_on_existing_resource_endpoint_documentation_support.rb create mode 100644 spec/swagger_schemas/filters/list_participant_declarations.rb create mode 100644 spec/swagger_schemas/models/participant_declaration.rb create mode 100644 spec/swagger_schemas/requests/participant_declaration_completed_request.rb create mode 100644 spec/swagger_schemas/requests/participant_declaration_request.rb create mode 100644 spec/swagger_schemas/requests/participant_declaration_retained_request.rb create mode 100644 spec/swagger_schemas/requests/participant_declaration_started_request.rb create mode 100644 spec/swagger_schemas/responses/participant_declaration.rb create mode 100644 spec/swagger_schemas/responses/participant_declarations.rb diff --git a/public/api/docs/v3/swagger.yaml b/public/api/docs/v3/swagger.yaml index ab4d57384e..a7560cc25d 100644 --- a/public/api/docs/v3/swagger.yaml +++ b/public/api/docs/v3/swagger.yaml @@ -797,6 +797,19 @@ components: description: Return only records that have this from Participant ID type: string example: 7e5bcdbf-c818-4961-8da5-439cab1984e0 + ListParticipantDeclarationsFilter: + description: Refine participant declarations to return. + type: object + properties: + participant_id: + description: The unique id of the participant + type: string + example: 7e5bcdbf-c818-4961-8da5-439cab1984e0 + updated_since: + description: Return only records that have been updated since this date + and time (ISO 8601 date format). + type: string + example: '2021-05-13T11:21:55Z' ListStatementsFilter: description: Filter statements to return more specific results type: object @@ -1765,3 +1778,423 @@ components: - "-created_at" - updated_at - "-updated_at" + ParticipantDeclaration: + description: The details of an NPQ Participant + type: object + required: + - id + - type + - attributes + properties: + id: + "$ref": "#/components/schemas/IDAttribute" + type: + description: The data type + type: string + example: npq-participant + enum: + - npq-participant + attributes: + properties: + full_name: + description: The full name of this NPQ participant + type: string + nullable: false + example: Isabelle MacDonald + teacher_reference_number: + description: The Teacher Reference Number (TRN) for this NPQ participant + type: string + example: '1234567' + updated_at: + description: The date the application was last updated + type: string + nullable: false + format: date-time + example: '2021-05-31T02:22:32.000Z' + npq_enrolments: + description: Information about the course(s) the participant is enroled + in + type: array + items: + description: The details of an NPQ Participant enrolment + type: object + required: + - email + - course_identifier + - npq_application_id + - eligible_for_funding + - training_status + - targeted_delivery_funding_eligibility + properties: + email: + description: The email address registered for this NPQ participant + type: string + nullable: false + example: isabelle.macdonald2@some-school.example.com + course_identifier: + description: The NPQ course this NPQ application relates to + type: string + nullable: false + example: npq-leading-teaching + enum: + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-senior-leadership + - npq-headship + - npq-executive-leadership + - npq-early-years-leadership + - npq-additional-support-offer + - npq-early-headship-coaching-offer + - npq-leading-primary-mathematics + - npq-senco + schedule_identifier: + description: The new schedule of the participant + nullable: true + type: string + example: npq-leadership-spring + enum: + - npq-aso-march + - npq-aso-june + - npq-aso-november + - npq-aso-december + - npq-ehco-march + - npq-ehco-june + - npq-ehco-november + - npq-ehco-december + - npq-leadership-autumn + - npq-leadership-spring + - npq-specialist-autumn + - npq-specialist-spring + cohort: + description: Indicates which call-off contract would fund this + participant's training. 2021 indicates a participant that has + started, or will start, their training in the 2021/22 academic + year. Once a provider accepts an application, they may change + a participant's cohort up until the point of submitting a started + declaration. + type: string + nullable: true + example: '2022' + eligible_for_funding: + description: Indicates whether this NPQ participant would be eligible + for funding from the DfE + type: boolean + nullable: false + example: true + npq_application_id: + description: The ID of the NPQ application that was accepted to + create this enrolment + type: string + format: uuid + nullable: false + example: db3a7848-7308-4879-942a-c4a70ced400a + training_status: + description: The training status of the NPQ participant + type: string + enum: + - active + - deferred + - withdrawn + example: active + school_urn: + description: The Unique Reference Number (URN) of the school where + this NPQ participant is employed + type: string + nullable: true + example: '106286' + targeted_delivery_funding_eligibility: + description: Whether or not this application is eligible for Targeted + Delivery Funding uplift + nullable: false + type: boolean + example: true + withdrawal: + description: The details of an NPQ Participant withdrawal + type: object + nullable: true + required: + - reason + - date + example: + properties: + reason: + description: The reason a participant was withdrawn + type: string + nullable: false + example: personal-reason-moving-school + enum: + - insufficient-capacity-to-undertake-programme + - personal-reason-health-or-pregnancy-related + - personal-reason-moving-school + - personal-reason-other + - insufficient-capacity + - change-in-developmental-or-personal-priorities + - change-in-school-circumstances + - change-in-school-leadership + - quality-of-programme-structure-not-suitable. + - quality-of-programme-content-not-suitable + - quality-of-programme-facilitation-not-effective + - quality-of-programme-accessibility + - quality-of-programme-other + - programme-not-appropriate-for-role-and-cpd-needs + - started-in-error + - expected-commitment-unclear + - other + date: + description: The date and time the participant was withdrawn + type: string + nullable: false + format: date-time + example: '2021-05-31T02:22:32.000Z' + deferral: + description: The details of an NPQ Participant deferral + type: object + nullable: true + required: + - reason + - date + example: + properties: + reason: + description: The reason a participant was deferred + type: string + nullable: false + example: career-break + enum: + - bereavement + - long-term-sickness + - parental-leave + - career-break + - other + date: + description: The date and time the participant was deferred + type: string + nullable: false + format: date-time + example: '2021-05-31T02:22:32.000Z' + created_at: + description: The date the application was created + type: string + nullable: false + format: date-time + example: '2021-05-31T02:21:32.000Z' + funded_place: + description: Indicates whether this NPQ participant is funded + by DfE + nullable: true + type: boolean + example: true + participant_id_changes: + description: Information about the Participant ID changes + type: array + items: + description: The details of an Participant ID change + type: object + required: + - from_participant_id + - to_participant_id + - changed_at + properties: + from_participant_id: + description: The unique identifier of the changed from participant + training record. + type: string + format: uuid + example: 23dd8d66-e11f-4139-9001-86b4f9abcb02 + to_participant_id: + description: The unique identifier of the changed to participant + training record. + type: string + format: uuid + example: ac3d1243-7308-4879-942a-c4a70ced400a + changed_at: + description: The date and time the Participant ID change + type: string + format: date-time + example: '2021-05-31T02:22:32.000Z' + ParticipantDeclarationRequest: + description: A participant declaration data request + type: object + properties: + type: + type: string + enum: + - participant-declaration + example: participant-declaration + attributes: + anyOf: + - "$ref": "#/components/schemas/ParticipantDeclarationStartedRequest" + - "$ref": "#/components/schemas/ParticipantDeclarationRetainedRequest" + - "$ref": "#/components/schemas/ParticipantDeclarationCompletedRequest" + ParticipantDeclarationResponse: + description: A single participant declaration. + type: object + required: + - data + properties: + data: + "$ref": "#/components/schemas/ParticipantDeclaration" + ParticipantDeclarationsResponse: + description: A list of participant declarations. + type: object + required: + - data + properties: + data: + type: array + items: + "$ref": "#/components/schemas/ParticipantDeclaration" + ParticipantDeclarationStartedRequest: + description: An NPQ started participant declaration + type: object + additionalProperties: false + properties: + participant_id: + description: The unique id of the participant + type: string + format: uuid + example: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: + description: The event declaration type + type: string + enum: + - started + example: started + declaration_date: + description: The event declaration date + type: string + format: date-time + example: '2021-05-31T02:21:32.000Z' + course_identifier: + description: The type of course the participant is enrolled in + type: string + enum: + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-senior-leadership + - npq-headship + - npq-executive-leadership + - npq-early-years-leadership + - npq-additional-support-offer + - npq-early-headship-coaching-offer + - npq-leading-primary-mathematics + - npq-senco + example: npq-headship + required: + - participant_id + - declaration_type + - declaration_date + - course_identifier + example: + participant_id: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: started + declaration_date: '2021-05-31T02:21:32.000Z' + course_identifier: npq-leading-teaching + ParticipantDeclarationRetainedRequest: + description: An NPQ participant retained declaration + type: object + additionalProperties: false + properties: + participant_id: + description: The unique id of the participant + type: string + format: uuid + example: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: + description: The event declaration type + type: string + enum: + - retained-1 + - retained-2 + example: retained-1 + declaration_date: + description: The event declaration date + type: string + format: date-time + example: '2021-05-31T02:21:32.000Z' + course_identifier: + description: The type of course the participant is enrolled in + type: string + enum: + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-senior-leadership + - npq-headship + - npq-executive-leadership + - npq-early-years-leadership + - npq-additional-support-offer + - npq-early-headship-coaching-offer + - npq-leading-primary-mathematics + - npq-senco + example: npq-headship + required: + - participant_id + - declaration_type + - declaration_date + - course_identifier + example: + participant_id: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: retained-1 + declaration_date: '2021-05-31T02:21:32.000Z' + course_identifier: npq-headship + ParticipantDeclarationCompletedRequest: + description: An NPQ completed participant declaration + type: object + required: + - participant_id + - declaration_type + - declaration_date + - course_identifier + - has_passed + additionalProperties: false + properties: + participant_id: + description: The unique id of the participant + type: string + format: uuid + example: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: + description: The event declaration type + type: string + enum: + - completed + example: completed + declaration_date: + description: The event declaration date + type: string + format: date-time + example: '2021-05-31T02:21:32.000Z' + course_identifier: + description: The type of course the participant is enrolled in + type: string + enum: + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-senior-leadership + - npq-headship + - npq-executive-leadership + - npq-early-years-leadership + - npq-additional-support-offer + - npq-early-headship-coaching-offer + - npq-leading-primary-mathematics + - npq-senco + example: npq-headship + has_passed: + description: Whether the participant has failed or passed + type: boolean + example: true + nullable: true + example: + participant_id: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: completed + declaration_date: '2021-05-31T02:21:32.000Z' + course_identifier: npq-leading-teaching + has_passed: true diff --git a/spec/requests/api/docs/v1/applications_spec.rb b/spec/requests/api/docs/v1/applications_spec.rb index 6e6e6b5d7a..2b53f21433 100644 --- a/spec/requests/api/docs/v1/applications_spec.rb +++ b/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", diff --git a/spec/requests/api/docs/v1/declarations_spec.rb b/spec/requests/api/docs/v1/declarations_spec.rb index da843ae6d8..6231ca13d1 100644 --- a/spec/requests/api/docs/v1/declarations_spec.rb +++ b/spec/requests/api/docs/v1/declarations_spec.rb @@ -9,4 +9,62 @@ "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 } + + 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" + 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 diff --git a/spec/requests/api/docs/v2/applications_spec.rb b/spec/requests/api/docs/v2/applications_spec.rb index da25e0adf8..b5e297498e 100644 --- a/spec/requests/api/docs/v2/applications_spec.rb +++ b/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", diff --git a/spec/requests/api/docs/v3/applications_spec.rb b/spec/requests/api/docs/v3/applications_spec.rb index 2b74e45f05..0d885402c2 100644 --- a/spec/requests/api/docs/v3/applications_spec.rb +++ b/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", diff --git a/spec/requests/api/docs/v3/declarations_spec.rb b/spec/requests/api/docs/v3/declarations_spec.rb new file mode 100644 index 0000000000..1c9da8ed9c --- /dev/null +++ b/spec/requests/api/docs/v3/declarations_spec.rb @@ -0,0 +1,6 @@ +require "rails_helper" +require "swagger_helper" + +RSpec.describe "Participant Declarations endpoint", type: :request, openapi_spec: "v1/swagger.yaml" do + include_context "with authorization for api doc request" +end diff --git a/spec/support/shared_examples/api_create_on_existing_resource_endpoint_documentation_support.rb b/spec/support/shared_examples/api_create_on_existing_resource_endpoint_documentation_support.rb new file mode 100644 index 0000000000..7580cdac72 --- /dev/null +++ b/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 diff --git a/spec/support/shared_examples/api_create_on_resource_endpoint_documentation_support.rb b/spec/support/shared_examples/api_create_on_resource_endpoint_documentation_support.rb index a0fa6ab9c5..0c2b60b614 100644 --- a/spec/support/shared_examples/api_create_on_resource_endpoint_documentation_support.rb +++ b/spec/support/shared_examples/api_create_on_resource_endpoint_documentation_support.rb @@ -8,13 +8,6 @@ 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, @@ -35,8 +28,6 @@ end response "200", response_description do - let(:id) { resource.ecf_id } - schema({ "$ref": response_schema_ref }) after do |example| @@ -58,7 +49,6 @@ end response "401", "Unauthorized" do - let(:id) { resource.ecf_id } let(:token) { "invalid" } schema({ "$ref": "#/components/schemas/UnauthorisedResponse" }) @@ -68,7 +58,6 @@ if request_schema_ref response "400", "Bad request" do - let(:id) { resource.ecf_id } let(:params) { { data: {} } } schema({ "$ref": "#/components/schemas/BadRequestResponse" }) @@ -77,7 +66,6 @@ end response "422", "Unprocessable entity" do - let(:id) { resource.ecf_id } let(:attributes) { invalid_attributes } schema({ "$ref": "#/components/schemas/UnprocessableEntityResponse" }) @@ -85,14 +73,6 @@ 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 diff --git a/spec/support/shared_examples/api_update_endpoint_documentation_support.rb b/spec/support/shared_examples/api_update_endpoint_documentation_support.rb index e6457d2e7b..b337f465eb 100644 --- a/spec/support/shared_examples/api_update_endpoint_documentation_support.rb +++ b/spec/support/shared_examples/api_update_endpoint_documentation_support.rb @@ -15,21 +15,23 @@ "$ref": "#/components/schemas/IDAttribute", } - parameter name: :params, - in: :body, - style: :deepObject, - required: true, - schema: { - "$ref": request_schema_ref, - } - - let(:params) do - { - data: { - type:, - attributes:, - }, - } + if request_schema_ref.present? + parameter name: :params, + in: :body, + style: :deepObject, + required: true, + schema: { + "$ref": request_schema_ref, + } + + let(:params) do + { + data: { + type:, + attributes:, + }, + } + end end response "200", response_description do @@ -64,22 +66,24 @@ run_test! end - response "400", "Bad request" do - let(:id) { resource.ecf_id } - let(:params) { { data: {} } } + if request_schema_ref.present? + response "400", "Bad request" do + let(:id) { resource.ecf_id } + let(:params) { { data: {} } } - schema({ "$ref": "#/components/schemas/BadRequestResponse" }) + schema({ "$ref": "#/components/schemas/BadRequestResponse" }) - run_test! - end + run_test! + end - response "422", "Unprocessable entity" do - let(:id) { resource.ecf_id } - let(:attributes) { invalid_attributes } + response "422", "Unprocessable entity" do + let(:id) { resource.ecf_id } + let(:attributes) { invalid_attributes } - schema({ "$ref": "#/components/schemas/UnprocessableEntityResponse" }) + schema({ "$ref": "#/components/schemas/UnprocessableEntityResponse" }) - run_test! + run_test! + end end response "404", "Not found", exceptions_app: true do diff --git a/spec/swagger_helper.rb b/spec/swagger_helper.rb index ae75cce37a..3fccd253ed 100644 --- a/spec/swagger_helper.rb +++ b/spec/swagger_helper.rb @@ -50,6 +50,7 @@ ListApplicationsFilter: LIST_APPLICATIONS_FILTER[version], ListEnrolmentsFilter: LIST_ENROLMENTS_FILTER[version], ListParticipantsFilter: LIST_PARTICIPANTS_FILTER[version], + ListParticipantDeclarationsFilter: LIST_PARTICIPANT_DECLARATIONS_FILTER[version], ListStatementsFilter: LIST_STATEMENTS_FILTER[version], UnauthorisedResponse: UNAUTHORISED_RESPONSE, NotFoundResponse: NOT_FOUND_RESPONSE, @@ -78,6 +79,14 @@ StatementsResponse: STATEMENTS_RESPONSE[version], Statement: STATEMENT[version], SortingOptions: SORTING_OPTIONS[version], + + ParticipantDeclaration: PARTICIPANT_DECLARATION[version], + ParticipantDeclarationRequest: PARTICIPANT_DECLARATION_REQUEST, + ParticipantDeclarationResponse: PARTICIPANT_DECLARATION_RESPONSE[version], + ParticipantDeclarationsResponse: PARTICIPANT_DECLARATIONS_RESPONSE[version], + ParticipantDeclarationStartedRequest: PARTICIPANT_DECLARATION_STARTED_REQUEST, + ParticipantDeclarationRetainedRequest: PARTICIPANT_DECLARATION_RETAINED_REQUEST, + ParticipantDeclarationCompletedRequest: PARTICIPANT_DECLARATION_COMPLETED_REQUEST, }.compact, }, } diff --git a/spec/swagger_schemas/filters/list_participant_declarations.rb b/spec/swagger_schemas/filters/list_participant_declarations.rb new file mode 100644 index 0000000000..fe99df9951 --- /dev/null +++ b/spec/swagger_schemas/filters/list_participant_declarations.rb @@ -0,0 +1,21 @@ +LIST_PARTICIPANT_DECLARATIONS_FILTER = { + v1: { + description: "Refine participant declarations to return.", + type: :object, + properties: { + participant_id: { + description: "The unique id of the participant", + type: :string, + example: "7e5bcdbf-c818-4961-8da5-439cab1984e0", + }, + updated_since: { + description: "Return only records that have been updated since this date and time (ISO 8601 date format).", + type: :string, + example: "2021-05-13T11:21:55Z", + }, + }, + }, +}.tap { |h| + h[:v2] = h[:v1] + h[:v3] = h[:v1] +}.freeze diff --git a/spec/swagger_schemas/models/participant_declaration.rb b/spec/swagger_schemas/models/participant_declaration.rb new file mode 100644 index 0000000000..582c2522a4 --- /dev/null +++ b/spec/swagger_schemas/models/participant_declaration.rb @@ -0,0 +1,505 @@ +PARTICIPANT_DECLARATION = { + v1: { + description: "The details of a participant declaration", + type: :object, + required: %i[id type attributes], + properties: { + id: { + "$ref": "#/components/schemas/IDAttribute", + }, + type: { + type: :string, + example: "participant-declaration", + }, + attributes: { + properties: { + participant_id: { + description: "The unique identifier of this participant declaration record", + type: :string, + format: :uuid, + nullable: false, + example: "db3a7848-7308-4879-942a-c4a70ced400a", + }, + declaration_type: { + description: "The event declaration type", + type: :string, + nullable: false, + example: "started", + enum: %w[ + started + retained-1 + retained-2 + retained-3 + retained-4 + completed + extended-1 + extended-2 + extended-3 + ], + }, + declaration_date: { + description: "The event declaration date", + type: :string, + nullable: false, + example: "2022-04-30", + }, + course_identifier: { + description: "The NPQ course this NPQ application relates to", + type: :string, + nullable: false, + example: "npq-leading-teaching", + enum: %w[ + npq-leading-teaching + npq-leading-behaviour-culture + npq-leading-teaching-development + npq-leading-literacy + npq-senior-leadership + npq-headship + npq-executive-leadership + npq-early-years-leadership + npq-additional-support-offer + npq-early-headship-coaching-offer + npq-leading-primary-mathematics + npq-senco + ], + }, + eligible_for_payment: { + description: "[Deprecated - use state instead] Indicates whether this declaration would be eligible for funding from the DfE", + type: :boolean, + nullable: true, + example: true, + }, + voided: { + description: "[Deprecated - use state instead] Indicates whether this declaration has been voided", + type: :boolean, + nullable: true, + example: true, + }, + state: { + description: "Indicates the state of this payment declaration", + type: :string, + nullable: false, + example: "submitted", + enum: %w[ + submitted + eligible + payable + paid + voided + ineligible + awaiting-clawback + clawed-back + ], + }, + updated_at: { + description: "The date the application was last updated", + type: :string, + nullable: false, + format: :"date-time", + example: "2021-05-31T02:22:32.000Z", + }, + has_passed: { + description: "The date the declaration was last updated", + type: :string, + nullable: true, + example: true, + }, + }, + }, + }, + }, + v2: { + description: "The details of an NPQ Participant", + type: :object, + required: %i[id type attributes], + properties: { + id: { + "$ref": "#/components/schemas/IDAttribute", + }, + type: { + description: "The data type", + type: :string, + example: "npq-participant", + enum: %w[ + npq-participant + ], + }, + attributes: { + properties: { + email: { + description: "The email address registered for this NPQ participant", + type: :string, + nullable: false, + example: "isabelle.macdonald2@some-school.example.com", + }, + full_name: { + description: "The full name of this NPQ participant", + type: :string, + nullable: false, + example: "Isabelle MacDonald", + }, + teacher_reference_number: { + description: "The Teacher Reference Number (TRN) for this NPQ participant", + type: :string, + example: "1234567", + }, + updated_at: { + description: "The date the application was last updated", + type: :string, + nullable: false, + format: :"date-time", + example: "2021-05-31T02:22:32.000Z", + }, + npq_enrolments: { + description: "Information about the course(s) the participant is enroled in", + type: :array, + items: { + description: "The details of an NPQ Participant enrolment", + type: :object, + required: %i[course_identifier npq_application_id eligible_for_funding training_status targeted_delivery_funding_eligibility], + properties: { + course_identifier: { + description: "The NPQ course this NPQ application relates to", + type: :string, + nullable: false, + example: "npq-leading-teaching", + enum: %w[ + npq-leading-teaching + npq-leading-behaviour-culture + npq-leading-teaching-development + npq-leading-literacy + npq-senior-leadership + npq-headship + npq-executive-leadership + npq-early-years-leadership + npq-additional-support-offer + npq-early-headship-coaching-offer + npq-leading-primary-mathematics + npq-senco + ], + }, + schedule_identifier: { + description: "The new schedule of the participant", + nullable: true, + type: :string, + example: "npq-leadership-spring", + enum: %w[ + npq-aso-march + npq-aso-june + npq-aso-november + npq-aso-december + npq-ehco-march + npq-ehco-june + npq-ehco-november + npq-ehco-december + npq-leadership-autumn + npq-leadership-spring + npq-specialist-autumn + npq-specialist-spring + ], + }, + cohort: { + description: "Indicates which call-off contract would fund this participant's training. 2021 indicates a participant that has started, or will start, their training in the 2021/22 academic year. Once a provider accepts an application, they may change a participant's cohort up until the point of submitting a started declaration.", + type: :string, + nullable: true, + example: "2022", + }, + eligible_for_funding: { + description: "Indicates whether this NPQ participant would be eligible for funding from the DfE", + type: :boolean, + nullable: false, + example: true, + }, + npq_application_id: { + description: "The ID of the NPQ application that was accepted to create this enrolment", + type: :string, + format: :uuid, + nullable: false, + example: "db3a7848-7308-4879-942a-c4a70ced400a", + }, + training_status: { + description: "The training status of the NPQ participant", + type: :string, + enum: %w[ + active + deferred + withdrawn + ], + example: "active", + }, + school_urn: { + description: "The Unique Reference Number (URN) of the school where this NPQ participant is employed", + type: :string, + nullable: true, + example: "106286", + }, + targeted_delivery_funding_eligibility: { + description: "Whether or not this application is eligible for Targeted Delivery Funding uplift", + nullable: false, + type: :boolean, + example: true, + }, + funded_place: { + description: "Indicates whether this NPQ participant is funded by DfE", + nullable: true, + type: :boolean, + example: true, + }, + }, + }, + }, + }, + }, + }, + }, + v3: { + description: "The details of an NPQ Participant", + type: :object, + required: %i[id type attributes], + properties: { + id: { + "$ref": "#/components/schemas/IDAttribute", + }, + type: { + description: "The data type", + type: :string, + example: "npq-participant", + enum: %w[ + npq-participant + ], + }, + attributes: { + properties: { + full_name: { + description: "The full name of this NPQ participant", + type: :string, + nullable: false, + example: "Isabelle MacDonald", + }, + teacher_reference_number: { + description: "The Teacher Reference Number (TRN) for this NPQ participant", + type: :string, + example: "1234567", + }, + updated_at: { + description: "The date the application was last updated", + type: :string, + nullable: false, + format: :"date-time", + example: "2021-05-31T02:22:32.000Z", + }, + npq_enrolments: { + description: "Information about the course(s) the participant is enroled in", + type: :array, + items: { + description: "The details of an NPQ Participant enrolment", + type: :object, + required: %i[email course_identifier npq_application_id eligible_for_funding training_status targeted_delivery_funding_eligibility], + properties: { + email: { + description: "The email address registered for this NPQ participant", + type: :string, + nullable: false, + example: "isabelle.macdonald2@some-school.example.com", + }, + course_identifier: { + description: "The NPQ course this NPQ application relates to", + type: :string, + nullable: false, + example: "npq-leading-teaching", + enum: %w[ + npq-leading-teaching + npq-leading-behaviour-culture + npq-leading-teaching-development + npq-leading-literacy + npq-senior-leadership + npq-headship + npq-executive-leadership + npq-early-years-leadership + npq-additional-support-offer + npq-early-headship-coaching-offer + npq-leading-primary-mathematics + npq-senco + ], + }, + schedule_identifier: { + description: "The new schedule of the participant", + nullable: true, + type: :string, + example: "npq-leadership-spring", + enum: %w[ + npq-aso-march + npq-aso-june + npq-aso-november + npq-aso-december + npq-ehco-march + npq-ehco-june + npq-ehco-november + npq-ehco-december + npq-leadership-autumn + npq-leadership-spring + npq-specialist-autumn + npq-specialist-spring + ], + }, + cohort: { + description: "Indicates which call-off contract would fund this participant's training. 2021 indicates a participant that has started, or will start, their training in the 2021/22 academic year. Once a provider accepts an application, they may change a participant's cohort up until the point of submitting a started declaration.", + type: :string, + nullable: true, + example: "2022", + }, + eligible_for_funding: { + description: "Indicates whether this NPQ participant would be eligible for funding from the DfE", + type: :boolean, + nullable: false, + example: true, + }, + npq_application_id: { + description: "The ID of the NPQ application that was accepted to create this enrolment", + type: :string, + format: :uuid, + nullable: false, + example: "db3a7848-7308-4879-942a-c4a70ced400a", + }, + training_status: { + description: "The training status of the NPQ participant", + type: :string, + enum: %w[ + active + deferred + withdrawn + ], + example: "active", + }, + school_urn: { + description: "The Unique Reference Number (URN) of the school where this NPQ participant is employed", + type: :string, + nullable: true, + example: "106286", + }, + targeted_delivery_funding_eligibility: { + description: "Whether or not this application is eligible for Targeted Delivery Funding uplift", + nullable: false, + type: :boolean, + example: true, + }, + withdrawal: { + description: "The details of an NPQ Participant withdrawal", + type: :object, + nullable: true, + required: %i[reason date], + example: nil, + properties: { + reason: { + description: "The reason a participant was withdrawn", + type: :string, + nullable: false, + example: "personal-reason-moving-school", + enum: %w[ + insufficient-capacity-to-undertake-programme + personal-reason-health-or-pregnancy-related + personal-reason-moving-school + personal-reason-other + insufficient-capacity + change-in-developmental-or-personal-priorities + change-in-school-circumstances + change-in-school-leadership + quality-of-programme-structure-not-suitable. + quality-of-programme-content-not-suitable + quality-of-programme-facilitation-not-effective + quality-of-programme-accessibility + quality-of-programme-other + programme-not-appropriate-for-role-and-cpd-needs + started-in-error + expected-commitment-unclear + other + ], + }, + date: { + description: "The date and time the participant was withdrawn", + type: :string, + nullable: false, + format: :"date-time", + example: "2021-05-31T02:22:32.000Z", + }, + }, + }, + deferral: { + description: "The details of an NPQ Participant deferral", + type: :object, + nullable: true, + required: %i[reason date], + example: nil, + properties: { + reason: { + description: "The reason a participant was deferred", + type: :string, + nullable: false, + example: "career-break", + enum: %w[ + bereavement + long-term-sickness + parental-leave + career-break + other + ], + }, + date: { + description: "The date and time the participant was deferred", + type: :string, + nullable: false, + format: :"date-time", + example: "2021-05-31T02:22:32.000Z", + }, + }, + }, + created_at: { + description: "The date the application was created", + type: :string, + nullable: false, + format: :"date-time", + example: "2021-05-31T02:21:32.000Z", + }, + funded_place: { + description: "Indicates whether this NPQ participant is funded by DfE", + nullable: true, + type: :boolean, + example: true, + }, + }, + }, + }, + participant_id_changes: { + description: "Information about the Participant ID changes", + type: :array, + items: { + description: "The details of an Participant ID change", + type: :object, + required: %i[from_participant_id to_participant_id changed_at], + properties: { + from_participant_id: { + description: "The unique identifier of the changed from participant training record.", + type: :string, + format: :uuid, + example: "23dd8d66-e11f-4139-9001-86b4f9abcb02", + }, + to_participant_id: { + description: "The unique identifier of the changed to participant training record.", + type: :string, + format: :uuid, + example: "ac3d1243-7308-4879-942a-c4a70ced400a", + }, + changed_at: { + description: "The date and time the Participant ID change", + type: :string, + format: :"date-time", + example: "2021-05-31T02:22:32.000Z", + }, + }, + }, + }, + }, + }, + }, + }, +}.freeze diff --git a/spec/swagger_schemas/requests/participant_declaration_completed_request.rb b/spec/swagger_schemas/requests/participant_declaration_completed_request.rb new file mode 100644 index 0000000000..2e2686e643 --- /dev/null +++ b/spec/swagger_schemas/requests/participant_declaration_completed_request.rb @@ -0,0 +1,66 @@ +PARTICIPANT_DECLARATION_COMPLETED_REQUEST = { + description: "An NPQ completed participant declaration", + type: :object, + required: %i[ + participant_id + declaration_type + declaration_date + course_identifier + has_passed + ], + additionalProperties: false, + properties: { + participant_id: { + description: "The unique id of the participant", + type: :string, + format: :uuid, + example: "db3a7848-7308-4879-942a-c4a70ced400a", + }, + declaration_type: { + description: "The event declaration type", + type: :string, + enum: %w[ + completed + ], + example: "completed", + }, + declaration_date: { + description: "The event declaration date", + type: :string, + format: "date-time", + example: "2021-05-31T02:21:32.000Z", + }, + course_identifier: { + description: "The type of course the participant is enrolled in", + type: :string, + enum: %w[ + npq-leading-teaching + npq-leading-behaviour-culture + npq-leading-teaching-development + npq-leading-literacy + npq-senior-leadership + npq-headship + npq-executive-leadership + npq-early-years-leadership + npq-additional-support-offer + npq-early-headship-coaching-offer + npq-leading-primary-mathematics + npq-senco + ], + example: "npq-headship", + }, + has_passed: { + description: "Whether the participant has failed or passed", + type: :boolean, + example: true, + nullable: true, + }, + }, + example: { + participant_id: "db3a7848-7308-4879-942a-c4a70ced400a", + declaration_type: "completed", + declaration_date: "2021-05-31T02:21:32.000Z", + course_identifier: "npq-leading-teaching", + has_passed: true, + }, +}.freeze diff --git a/spec/swagger_schemas/requests/participant_declaration_request.rb b/spec/swagger_schemas/requests/participant_declaration_request.rb new file mode 100644 index 0000000000..76cb809a7c --- /dev/null +++ b/spec/swagger_schemas/requests/participant_declaration_request.rb @@ -0,0 +1,20 @@ +PARTICIPANT_DECLARATION_REQUEST = { + description: "A participant declaration data request", + type: :object, + properties: { + type: { + type: :string, + enum: %w[ + participant-declaration + ], + example: "participant-declaration", + }, + attributes: { + anyOf: [ + { "$ref": "#/components/schemas/ParticipantDeclarationStartedRequest" }, + { "$ref": "#/components/schemas/ParticipantDeclarationRetainedRequest" }, + { "$ref": "#/components/schemas/ParticipantDeclarationCompletedRequest" }, + ], + }, + }, +}.freeze diff --git a/spec/swagger_schemas/requests/participant_declaration_retained_request.rb b/spec/swagger_schemas/requests/participant_declaration_retained_request.rb new file mode 100644 index 0000000000..3d6c644128 --- /dev/null +++ b/spec/swagger_schemas/requests/participant_declaration_retained_request.rb @@ -0,0 +1,59 @@ +PARTICIPANT_DECLARATION_RETAINED_REQUEST = { + description: "An NPQ participant retained declaration", + type: :object, + additionalProperties: false, + properties: { + participant_id: { + description: "The unique id of the participant", + type: :string, + format: :uuid, + example: "db3a7848-7308-4879-942a-c4a70ced400a", + }, + declaration_type: { + description: "The event declaration type", + type: :string, + enum: %w[ + retained-1 + retained-2 + ], + example: "retained-1", + }, + declaration_date: { + description: "The event declaration date", + type: :string, + format: "date-time", + example: "2021-05-31T02:21:32.000Z", + }, + course_identifier: { + description: "The type of course the participant is enrolled in", + type: :string, + enum: %w[ + npq-leading-teaching + npq-leading-behaviour-culture + npq-leading-teaching-development + npq-leading-literacy + npq-senior-leadership + npq-headship + npq-executive-leadership + npq-early-years-leadership + npq-additional-support-offer + npq-early-headship-coaching-offer + npq-leading-primary-mathematics + npq-senco + ], + example: "npq-headship", + }, + }, + required: %i[ + participant_id + declaration_type + declaration_date + course_identifier + ], + example: { + participant_id: "db3a7848-7308-4879-942a-c4a70ced400a", + declaration_type: "retained-1", + declaration_date: "2021-05-31T02:21:32.000Z", + course_identifier: "npq-headship", + }, +}.freeze diff --git a/spec/swagger_schemas/requests/participant_declaration_started_request.rb b/spec/swagger_schemas/requests/participant_declaration_started_request.rb new file mode 100644 index 0000000000..956f601d1a --- /dev/null +++ b/spec/swagger_schemas/requests/participant_declaration_started_request.rb @@ -0,0 +1,58 @@ +PARTICIPANT_DECLARATION_STARTED_REQUEST = { + description: "An NPQ started participant declaration", + type: :object, + additionalProperties: false, + properties: { + participant_id: { + description: "The unique id of the participant", + type: :string, + format: :uuid, + example: "db3a7848-7308-4879-942a-c4a70ced400a", + }, + declaration_type: { + description: "The event declaration type", + type: :string, + enum: %w[ + started + ], + example: "started", + }, + declaration_date: { + description: "The event declaration date", + type: :string, + format: "date-time", + example: "2021-05-31T02:21:32.000Z", + }, + course_identifier: { + description: "The type of course the participant is enrolled in", + type: :string, + enum: %w[ + npq-leading-teaching + npq-leading-behaviour-culture + npq-leading-teaching-development + npq-leading-literacy + npq-senior-leadership + npq-headship + npq-executive-leadership + npq-early-years-leadership + npq-additional-support-offer + npq-early-headship-coaching-offer + npq-leading-primary-mathematics + npq-senco + ], + example: "npq-headship", + }, + }, + required: %i[ + participant_id + declaration_type + declaration_date + course_identifier + ], + example: { + participant_id: "db3a7848-7308-4879-942a-c4a70ced400a", + declaration_type: "started", + declaration_date: "2021-05-31T02:21:32.000Z", + course_identifier: "npq-leading-teaching", + }, +}.freeze diff --git a/spec/swagger_schemas/responses/participant_declaration.rb b/spec/swagger_schemas/responses/participant_declaration.rb new file mode 100644 index 0000000000..efe3df90ae --- /dev/null +++ b/spec/swagger_schemas/responses/participant_declaration.rb @@ -0,0 +1,15 @@ +PARTICIPANT_DECLARATION_RESPONSE = { + v1: { + description: "A single participant declaration.", + type: :object, + required: %i[data], + properties: { + data: { + "$ref": "#/components/schemas/ParticipantDeclaration", + }, + }, + }, +}.tap { |h| + h[:v2] = h[:v1] + h[:v3] = h[:v1] +}.freeze diff --git a/spec/swagger_schemas/responses/participant_declarations.rb b/spec/swagger_schemas/responses/participant_declarations.rb new file mode 100644 index 0000000000..f138dbf4ae --- /dev/null +++ b/spec/swagger_schemas/responses/participant_declarations.rb @@ -0,0 +1,16 @@ +PARTICIPANT_DECLARATIONS_RESPONSE = { + v1: { + description: "A list of participant declarations.", + type: :object, + required: %i[data], + properties: { + data: { + type: :array, + items: { "$ref": "#/components/schemas/ParticipantDeclaration" }, + }, + }, + }, +}.tap { |h| + h[:v2] = h[:v1] + h[:v3] = h[:v1] +}.freeze From 73da60d6a870c7e3e3b8839a98642b1751ae0b48 Mon Sep 17 00:00:00 2001 From: Pablo M Date: Mon, 1 Jul 2024 09:42:32 +0100 Subject: [PATCH 02/11] Add Swagger support for V2 declarations --- public/api/docs/v2/swagger.yaml | 153 ++++++ .../requests/api/docs/v2/declarations_spec.rb | 58 +++ .../models/participant_declaration.rb | 459 ++++-------------- 3 files changed, 295 insertions(+), 375 deletions(-) diff --git a/public/api/docs/v2/swagger.yaml b/public/api/docs/v2/swagger.yaml index 314346ac92..5adbbf132a 100644 --- a/public/api/docs/v2/swagger.yaml +++ b/public/api/docs/v2/swagger.yaml @@ -319,6 +319,159 @@ paths: text/csv: schema: "$ref": "#/components/schemas/UnauthorisedResponse" + "/api/v2/participant-declarations": + get: + summary: Retrieve multiple Participant declarations + tags: + - Participant declarations + security: + - api_key: [] + parameters: + - name: filter + in: query + required: false + schema: + "$ref": "#/components/schemas/ListParticipantDeclarationsFilter" + - name: page + in: query + required: false + schema: + "$ref": "#/components/schemas/PaginationFilter" + responses: + '200': + description: A list of Participant declarations + content: + application/json: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationsResponse" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/UnauthorisedResponse" + post: + summary: Declare a participant has reached a milestone + tags: + - Participant declarations + security: + - api_key: [] + parameters: [] + responses: + '200': + description: The participant declaration being created + content: + application/json: + examples: + success: + value: + data: + id: d0b4a32e-a272-489e-b30a-cb17131457fc + type: npq-participant + attributes: + email: isabelle.macdonald2@some-school.example.com + full_name: Isabelle MacDonald + teacher_reference_number: '1234567' + updated_at: '2021-05-31T02:22:32.000Z' + npq_enrolments: + - course_identifier: npq-leading-teaching + schedule_identifier: npq-leadership-spring + cohort: '2022' + eligible_for_funding: true + npq_application_id: db3a7848-7308-4879-942a-c4a70ced400a + training_status: active + school_urn: '106286' + targeted_delivery_funding_eligibility: true + funded_place: true + schema: + "$ref": "#/components/schemas/ParticipantDeclarationResponse" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/UnauthorisedResponse" + '400': + description: Bad request + content: + application/json: + schema: + "$ref": "#/components/schemas/BadRequestResponse" + '422': + description: Unprocessable entity + content: + application/json: + schema: + "$ref": "#/components/schemas/UnprocessableEntityResponse" + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationRequest" + "/api/v2/participant-declarations/{id}": + get: + summary: Retrieve a single Participant declarations + tags: + - Participant declarations + security: + - api_key: [] + parameters: + - name: id + in: path + required: true + schema: + "$ref": "#/components/schemas/IDAttribute" + responses: + '200': + description: A single Participant declarations + content: + application/json: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationResponse" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/UnauthorisedResponse" + '404': + description: Not found + content: + application/json: + schema: + "$ref": "#/components/schemas/NotFoundResponse" + "/api/v2/participant-declarations/{id}/void": + put: + summary: Void a declaration + tags: + - Participant declarations + security: + - api_key: [] + parameters: + - name: id + in: path + required: true + schema: + "$ref": "#/components/schemas/IDAttribute" + responses: + '200': + description: The participant declaration being voided + content: + application/json: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationResponse" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/UnauthorisedResponse" + '404': + description: Not found + content: + application/json: + schema: + "$ref": "#/components/schemas/NotFoundResponse" "/api/v2/npq-enrolments.csv": get: summary: Retrieve all NPQ enrolments in CSV format diff --git a/spec/requests/api/docs/v2/declarations_spec.rb b/spec/requests/api/docs/v2/declarations_spec.rb index 60edd40dfd..e046364213 100644 --- a/spec/requests/api/docs/v2/declarations_spec.rb +++ b/spec/requests/api/docs/v2/declarations_spec.rb @@ -9,4 +9,62 @@ "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 } + + 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" + 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 diff --git a/spec/swagger_schemas/models/participant_declaration.rb b/spec/swagger_schemas/models/participant_declaration.rb index 582c2522a4..dd94a41359 100644 --- a/spec/swagger_schemas/models/participant_declaration.rb +++ b/spec/swagger_schemas/models/participant_declaration.rb @@ -8,8 +8,8 @@ "$ref": "#/components/schemas/IDAttribute", }, type: { + description: "The data type", type: :string, - example: "participant-declaration", }, attributes: { properties: { @@ -109,151 +109,94 @@ }, }, v2: { - description: "The details of an NPQ Participant", + description: "The data attributes associated with a participant declaration response", type: :object, required: %i[id type attributes], - properties: { - id: { - "$ref": "#/components/schemas/IDAttribute", - }, - type: { - description: "The data type", - type: :string, - example: "npq-participant", - enum: %w[ - npq-participant - ], - }, - attributes: { - properties: { - email: { - description: "The email address registered for this NPQ participant", - type: :string, - nullable: false, - example: "isabelle.macdonald2@some-school.example.com", - }, - full_name: { - description: "The full name of this NPQ participant", - type: :string, - nullable: false, - example: "Isabelle MacDonald", - }, - teacher_reference_number: { - description: "The Teacher Reference Number (TRN) for this NPQ participant", - type: :string, - example: "1234567", - }, - updated_at: { - description: "The date the application was last updated", - type: :string, - nullable: false, - format: :"date-time", - example: "2021-05-31T02:22:32.000Z", - }, - npq_enrolments: { - description: "Information about the course(s) the participant is enroled in", - type: :array, - items: { - description: "The details of an NPQ Participant enrolment", - type: :object, - required: %i[course_identifier npq_application_id eligible_for_funding training_status targeted_delivery_funding_eligibility], - properties: { - course_identifier: { - description: "The NPQ course this NPQ application relates to", - type: :string, - nullable: false, - example: "npq-leading-teaching", - enum: %w[ - npq-leading-teaching - npq-leading-behaviour-culture - npq-leading-teaching-development - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership - npq-additional-support-offer - npq-early-headship-coaching-offer - npq-leading-primary-mathematics - npq-senco - ], - }, - schedule_identifier: { - description: "The new schedule of the participant", - nullable: true, - type: :string, - example: "npq-leadership-spring", - enum: %w[ - npq-aso-march - npq-aso-june - npq-aso-november - npq-aso-december - npq-ehco-march - npq-ehco-june - npq-ehco-november - npq-ehco-december - npq-leadership-autumn - npq-leadership-spring - npq-specialist-autumn - npq-specialist-spring - ], - }, - cohort: { - description: "Indicates which call-off contract would fund this participant's training. 2021 indicates a participant that has started, or will start, their training in the 2021/22 academic year. Once a provider accepts an application, they may change a participant's cohort up until the point of submitting a started declaration.", - type: :string, - nullable: true, - example: "2022", - }, - eligible_for_funding: { - description: "Indicates whether this NPQ participant would be eligible for funding from the DfE", - type: :boolean, - nullable: false, - example: true, - }, - npq_application_id: { - description: "The ID of the NPQ application that was accepted to create this enrolment", - type: :string, - format: :uuid, - nullable: false, - example: "db3a7848-7308-4879-942a-c4a70ced400a", - }, - training_status: { - description: "The training status of the NPQ participant", - type: :string, - enum: %w[ - active - deferred - withdrawn - ], - example: "active", - }, - school_urn: { - description: "The Unique Reference Number (URN) of the school where this NPQ participant is employed", - type: :string, - nullable: true, - example: "106286", - }, - targeted_delivery_funding_eligibility: { - description: "Whether or not this application is eligible for Targeted Delivery Funding uplift", - nullable: false, - type: :boolean, - example: true, - }, - funded_place: { - description: "Indicates whether this NPQ participant is funded by DfE", - nullable: true, - type: :boolean, - example: true, - }, - }, - }, - }, + id: { + "$ref": "#/components/schemas/IDAttribute", + }, + type: { + description: "The data type", + type: :string, + }, + attributes: { + properties: { + participant_id: { + description: "The unique id of the participant", + type: :string, + format: :uuid, + example: "db3a7848-7308-4879-942a-c4a70ced400a", + }, + declaration_type: { + description: "The event declaration type", + type: :string, + enum: %w[ + started + retained-1 + retained-2 + retained-3 + retained-4 + completed + extended-1 + extended-2 + extended-3 + ], + example: "started", + }, + declaration_date: { + description: "The event declaration date", + type: :string, + format: "date-time", + example: "2021-05-31T02:21:32.000Z", + }, + course_identifier: { + description: "The type of course the participant is enrolled in", + type: :string, + enum: %w[ + npq-leading-teaching + npq-leading-behaviour-culture + npq-leading-teaching-development + npq-leading-literacy + npq-senior-leadership + npq-headship + npq-executive-leadership + npq-early-years-leadership + npq-additional-support-offer + npq-early-headship-coaching-offer + npq-leading-primary-mathematics + ], + example: "ecf-induction", + }, + state: { + description: "Indicates the state of this payment declaration", + type: :string, + enum: %w[ + submitted + eligible + payable + paid + voided + ineligible + ], + example: "submitted", + }, + updated_at: { + description: "The date the declaration was last updated", + type: :string, + format: "date-time", + example: "2021-05-31T02:22:32.000Z", + }, + has_passed: { + description: "Whether the participant has failed or passed", + type: :boolean, + example: true, + nullable: true, }, }, }, }, v3: { - description: "The details of an NPQ Participant", + description: "The details of a participant declaration", type: :object, required: %i[id type attributes], properties: { @@ -263,243 +206,9 @@ type: { description: "The data type", type: :string, - example: "npq-participant", - enum: %w[ - npq-participant - ], }, attributes: { - properties: { - full_name: { - description: "The full name of this NPQ participant", - type: :string, - nullable: false, - example: "Isabelle MacDonald", - }, - teacher_reference_number: { - description: "The Teacher Reference Number (TRN) for this NPQ participant", - type: :string, - example: "1234567", - }, - updated_at: { - description: "The date the application was last updated", - type: :string, - nullable: false, - format: :"date-time", - example: "2021-05-31T02:22:32.000Z", - }, - npq_enrolments: { - description: "Information about the course(s) the participant is enroled in", - type: :array, - items: { - description: "The details of an NPQ Participant enrolment", - type: :object, - required: %i[email course_identifier npq_application_id eligible_for_funding training_status targeted_delivery_funding_eligibility], - properties: { - email: { - description: "The email address registered for this NPQ participant", - type: :string, - nullable: false, - example: "isabelle.macdonald2@some-school.example.com", - }, - course_identifier: { - description: "The NPQ course this NPQ application relates to", - type: :string, - nullable: false, - example: "npq-leading-teaching", - enum: %w[ - npq-leading-teaching - npq-leading-behaviour-culture - npq-leading-teaching-development - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership - npq-additional-support-offer - npq-early-headship-coaching-offer - npq-leading-primary-mathematics - npq-senco - ], - }, - schedule_identifier: { - description: "The new schedule of the participant", - nullable: true, - type: :string, - example: "npq-leadership-spring", - enum: %w[ - npq-aso-march - npq-aso-june - npq-aso-november - npq-aso-december - npq-ehco-march - npq-ehco-june - npq-ehco-november - npq-ehco-december - npq-leadership-autumn - npq-leadership-spring - npq-specialist-autumn - npq-specialist-spring - ], - }, - cohort: { - description: "Indicates which call-off contract would fund this participant's training. 2021 indicates a participant that has started, or will start, their training in the 2021/22 academic year. Once a provider accepts an application, they may change a participant's cohort up until the point of submitting a started declaration.", - type: :string, - nullable: true, - example: "2022", - }, - eligible_for_funding: { - description: "Indicates whether this NPQ participant would be eligible for funding from the DfE", - type: :boolean, - nullable: false, - example: true, - }, - npq_application_id: { - description: "The ID of the NPQ application that was accepted to create this enrolment", - type: :string, - format: :uuid, - nullable: false, - example: "db3a7848-7308-4879-942a-c4a70ced400a", - }, - training_status: { - description: "The training status of the NPQ participant", - type: :string, - enum: %w[ - active - deferred - withdrawn - ], - example: "active", - }, - school_urn: { - description: "The Unique Reference Number (URN) of the school where this NPQ participant is employed", - type: :string, - nullable: true, - example: "106286", - }, - targeted_delivery_funding_eligibility: { - description: "Whether or not this application is eligible for Targeted Delivery Funding uplift", - nullable: false, - type: :boolean, - example: true, - }, - withdrawal: { - description: "The details of an NPQ Participant withdrawal", - type: :object, - nullable: true, - required: %i[reason date], - example: nil, - properties: { - reason: { - description: "The reason a participant was withdrawn", - type: :string, - nullable: false, - example: "personal-reason-moving-school", - enum: %w[ - insufficient-capacity-to-undertake-programme - personal-reason-health-or-pregnancy-related - personal-reason-moving-school - personal-reason-other - insufficient-capacity - change-in-developmental-or-personal-priorities - change-in-school-circumstances - change-in-school-leadership - quality-of-programme-structure-not-suitable. - quality-of-programme-content-not-suitable - quality-of-programme-facilitation-not-effective - quality-of-programme-accessibility - quality-of-programme-other - programme-not-appropriate-for-role-and-cpd-needs - started-in-error - expected-commitment-unclear - other - ], - }, - date: { - description: "The date and time the participant was withdrawn", - type: :string, - nullable: false, - format: :"date-time", - example: "2021-05-31T02:22:32.000Z", - }, - }, - }, - deferral: { - description: "The details of an NPQ Participant deferral", - type: :object, - nullable: true, - required: %i[reason date], - example: nil, - properties: { - reason: { - description: "The reason a participant was deferred", - type: :string, - nullable: false, - example: "career-break", - enum: %w[ - bereavement - long-term-sickness - parental-leave - career-break - other - ], - }, - date: { - description: "The date and time the participant was deferred", - type: :string, - nullable: false, - format: :"date-time", - example: "2021-05-31T02:22:32.000Z", - }, - }, - }, - created_at: { - description: "The date the application was created", - type: :string, - nullable: false, - format: :"date-time", - example: "2021-05-31T02:21:32.000Z", - }, - funded_place: { - description: "Indicates whether this NPQ participant is funded by DfE", - nullable: true, - type: :boolean, - example: true, - }, - }, - }, - }, - participant_id_changes: { - description: "Information about the Participant ID changes", - type: :array, - items: { - description: "The details of an Participant ID change", - type: :object, - required: %i[from_participant_id to_participant_id changed_at], - properties: { - from_participant_id: { - description: "The unique identifier of the changed from participant training record.", - type: :string, - format: :uuid, - example: "23dd8d66-e11f-4139-9001-86b4f9abcb02", - }, - to_participant_id: { - description: "The unique identifier of the changed to participant training record.", - type: :string, - format: :uuid, - example: "ac3d1243-7308-4879-942a-c4a70ced400a", - }, - changed_at: { - description: "The date and time the Participant ID change", - type: :string, - format: :"date-time", - example: "2021-05-31T02:22:32.000Z", - }, - }, - }, - }, - }, - }, - }, + + } }, }.freeze From 75fec8422fa67403a44e85d1fe5c813dfcce85b1 Mon Sep 17 00:00:00 2001 From: Pablo M Date: Wed, 3 Jul 2024 10:52:21 +0100 Subject: [PATCH 03/11] Add Swagger support for V3 declarations --- public/api/docs/v3/swagger.yaml | 487 ++++++++++-------- .../requests/api/docs/v3/declarations_spec.rb | 60 ++- .../filters/list_participant_declarations.rb | 14 +- .../models/participant_declaration.rb | 329 +++++++++--- 4 files changed, 587 insertions(+), 303 deletions(-) diff --git a/public/api/docs/v3/swagger.yaml b/public/api/docs/v3/swagger.yaml index a7560cc25d..d4365e324d 100644 --- a/public/api/docs/v3/swagger.yaml +++ b/public/api/docs/v3/swagger.yaml @@ -280,6 +280,163 @@ paths: schema: "$ref": "#/components/schemas/ApplicationChangeFundedPlaceRequest" required: true + "/api/v3/participant-declarations": + get: + summary: Retrieve multiple Participant declarations + tags: + - Participant declarations + security: + - api_key: [] + parameters: + - name: filter + in: query + required: false + schema: + "$ref": "#/components/schemas/ListParticipantDeclarationsFilter" + - name: page + in: query + required: false + schema: + "$ref": "#/components/schemas/PaginationFilter" + - name: sort + in: query + required: false + schema: + "$ref": "#/components/schemas/SortingOptions" + responses: + '200': + description: A list of Participant declarations + content: + application/json: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationsResponse" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/UnauthorisedResponse" + post: + summary: Declare a participant has reached a milestone + tags: + - Participant declarations + security: + - api_key: [] + parameters: [] + responses: + '200': + description: The participant declaration being created + content: + application/json: + examples: + success: + value: + data: + id: d0b4a32e-a272-489e-b30a-cb17131457fc + type: participant-declaration + attributes: + participant_id: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: started + declaration_date: '2021-05-31T02:21:32.000Z' + course_identifier: npq-leading-teaching + state: submitted + updated_at: '2021-05-31T02:22:32.000Z' + created_at: '2021-05-31T02:22:32.000Z' + statement_id: cd3a12347-7308-4879-942a-c4a70ced400a + clawback_statement_id: cd3a12347-7308-4879-942a-c4a70ced400a + ineligible_for_funding_reason: duplicate_declaration + uplift_paid: true + has_passed: true + lead_provider_name: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationResponse" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/UnauthorisedResponse" + '400': + description: Bad request + content: + application/json: + schema: + "$ref": "#/components/schemas/BadRequestResponse" + '422': + description: Unprocessable entity + content: + application/json: + schema: + "$ref": "#/components/schemas/UnprocessableEntityResponse" + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationRequest" + "/api/v3/participant-declarations/{id}": + get: + summary: Retrieve a single Participant declarations + tags: + - Participant declarations + security: + - api_key: [] + parameters: + - name: id + in: path + required: true + schema: + "$ref": "#/components/schemas/IDAttribute" + responses: + '200': + description: A single Participant declarations + content: + application/json: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationResponse" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/UnauthorisedResponse" + '404': + description: Not found + content: + application/json: + schema: + "$ref": "#/components/schemas/NotFoundResponse" + "/api/v3/participant-declarations/{id}/void": + put: + summary: Void a declaration + tags: + - Participant declarations + security: + - api_key: [] + parameters: + - name: id + in: path + required: true + schema: + "$ref": "#/components/schemas/IDAttribute" + responses: + '200': + description: The participant declaration being voided + content: + application/json: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationResponse" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/UnauthorisedResponse" + '404': + description: Not found + content: + application/json: + schema: + "$ref": "#/components/schemas/NotFoundResponse" "/api/v3/participants/npq": get: summary: Retrieve multiple NPQ participants @@ -810,6 +967,17 @@ components: and time (ISO 8601 date format). type: string example: '2021-05-13T11:21:55Z' + cohort: + description: Return participant declarations associated to the specified + cohort or cohorts. This is a comma delimited string of years. + type: string + example: '2021,2022' + delivery_partner_id: + description: Return participant declarations associated to the specified + delivery partner or delivery partners. This is a comma delimited string + of delivery partner IDs. + type: string + example: 7e5bcdbf-c818-4961-8da5-439cab1984e0 ListStatementsFilter: description: Filter statements to return more specific results type: object @@ -1779,7 +1947,7 @@ components: - updated_at - "-updated_at" ParticipantDeclaration: - description: The details of an NPQ Participant + description: The data attributes associated with a participant declaration response type: object required: - id @@ -1789,231 +1957,118 @@ components: id: "$ref": "#/components/schemas/IDAttribute" type: - description: The data type type: string - example: npq-participant enum: - - npq-participant + - participant-declaration + example: participant-declaration attributes: + required: + - participant_id + - declaration_type + - declaration_date + - course_identifier + - state + - updated_at + - lead_provider_name properties: - full_name: - description: The full name of this NPQ participant + participant_id: + description: The unique id of the participant type: string - nullable: false - example: Isabelle MacDonald - teacher_reference_number: - description: The Teacher Reference Number (TRN) for this NPQ participant + format: uuid + example: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: + description: The event declaration type type: string - example: '1234567' + enum: + - started + - retained-1 + - retained-2 + - retained-3 + - retained-4 + - completed + - extended-1 + - extended-2 + - extended-3 + example: started + declaration_date: + description: The event declaration date + type: string + format: date-time + example: '2021-05-31T02:21:32.000Z' + course_identifier: + description: The type of course the participant is enrolled in + type: string + enum: + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-senior-leadership + - npq-headship + - npq-executive-leadership + - npq-early-years-leadership + - npq-additional-support-offer + - npq-early-headship-coaching-offer + - npq-leading-primary-mathematics + example: npq-leading-teaching + state: + description: Indicates the state of this payment declaration + type: string + enum: + - submitted + - eligible + - payable + - paid + - voided + - ineligible + - awaiting-clawback + - clawed-back + example: submitted updated_at: - description: The date the application was last updated + description: The date the declaration was last updated type: string - nullable: false format: date-time example: '2021-05-31T02:22:32.000Z' - npq_enrolments: - description: Information about the course(s) the participant is enroled - in - type: array - items: - description: The details of an NPQ Participant enrolment - type: object - required: - - email - - course_identifier - - npq_application_id - - eligible_for_funding - - training_status - - targeted_delivery_funding_eligibility - properties: - email: - description: The email address registered for this NPQ participant - type: string - nullable: false - example: isabelle.macdonald2@some-school.example.com - course_identifier: - description: The NPQ course this NPQ application relates to - type: string - nullable: false - example: npq-leading-teaching - enum: - - npq-leading-teaching - - npq-leading-behaviour-culture - - npq-leading-teaching-development - - npq-leading-literacy - - npq-senior-leadership - - npq-headship - - npq-executive-leadership - - npq-early-years-leadership - - npq-additional-support-offer - - npq-early-headship-coaching-offer - - npq-leading-primary-mathematics - - npq-senco - schedule_identifier: - description: The new schedule of the participant - nullable: true - type: string - example: npq-leadership-spring - enum: - - npq-aso-march - - npq-aso-june - - npq-aso-november - - npq-aso-december - - npq-ehco-march - - npq-ehco-june - - npq-ehco-november - - npq-ehco-december - - npq-leadership-autumn - - npq-leadership-spring - - npq-specialist-autumn - - npq-specialist-spring - cohort: - description: Indicates which call-off contract would fund this - participant's training. 2021 indicates a participant that has - started, or will start, their training in the 2021/22 academic - year. Once a provider accepts an application, they may change - a participant's cohort up until the point of submitting a started - declaration. - type: string - nullable: true - example: '2022' - eligible_for_funding: - description: Indicates whether this NPQ participant would be eligible - for funding from the DfE - type: boolean - nullable: false - example: true - npq_application_id: - description: The ID of the NPQ application that was accepted to - create this enrolment - type: string - format: uuid - nullable: false - example: db3a7848-7308-4879-942a-c4a70ced400a - training_status: - description: The training status of the NPQ participant - type: string - enum: - - active - - deferred - - withdrawn - example: active - school_urn: - description: The Unique Reference Number (URN) of the school where - this NPQ participant is employed - type: string - nullable: true - example: '106286' - targeted_delivery_funding_eligibility: - description: Whether or not this application is eligible for Targeted - Delivery Funding uplift - nullable: false - type: boolean - example: true - withdrawal: - description: The details of an NPQ Participant withdrawal - type: object - nullable: true - required: - - reason - - date - example: - properties: - reason: - description: The reason a participant was withdrawn - type: string - nullable: false - example: personal-reason-moving-school - enum: - - insufficient-capacity-to-undertake-programme - - personal-reason-health-or-pregnancy-related - - personal-reason-moving-school - - personal-reason-other - - insufficient-capacity - - change-in-developmental-or-personal-priorities - - change-in-school-circumstances - - change-in-school-leadership - - quality-of-programme-structure-not-suitable. - - quality-of-programme-content-not-suitable - - quality-of-programme-facilitation-not-effective - - quality-of-programme-accessibility - - quality-of-programme-other - - programme-not-appropriate-for-role-and-cpd-needs - - started-in-error - - expected-commitment-unclear - - other - date: - description: The date and time the participant was withdrawn - type: string - nullable: false - format: date-time - example: '2021-05-31T02:22:32.000Z' - deferral: - description: The details of an NPQ Participant deferral - type: object - nullable: true - required: - - reason - - date - example: - properties: - reason: - description: The reason a participant was deferred - type: string - nullable: false - example: career-break - enum: - - bereavement - - long-term-sickness - - parental-leave - - career-break - - other - date: - description: The date and time the participant was deferred - type: string - nullable: false - format: date-time - example: '2021-05-31T02:22:32.000Z' - created_at: - description: The date the application was created - type: string - nullable: false - format: date-time - example: '2021-05-31T02:21:32.000Z' - funded_place: - description: Indicates whether this NPQ participant is funded - by DfE - nullable: true - type: boolean - example: true - participant_id_changes: - description: Information about the Participant ID changes - type: array - items: - description: The details of an Participant ID change - type: object - required: - - from_participant_id - - to_participant_id - - changed_at - properties: - from_participant_id: - description: The unique identifier of the changed from participant - training record. - type: string - format: uuid - example: 23dd8d66-e11f-4139-9001-86b4f9abcb02 - to_participant_id: - description: The unique identifier of the changed to participant - training record. - type: string - format: uuid - example: ac3d1243-7308-4879-942a-c4a70ced400a - changed_at: - description: The date and time the Participant ID change - type: string - format: date-time - example: '2021-05-31T02:22:32.000Z' + created_at: + description: The date the declaration was created + type: string + format: date-time + example: '2021-05-31T02:22:32.000Z' + statement_id: + description: Unique ID of the statement the declaration will be paid + as part of + type: string + format: uuid + example: cd3a12347-7308-4879-942a-c4a70ced400a + nullable: true + clawback_statement_id: + description: Unique id of the statement to which the declaration will + be clawed back on, if any + type: string + format: uuid + example: cd3a12347-7308-4879-942a-c4a70ced400a + nullable: true + ineligible_for_funding_reason: + description: If the declaration is ineligible, the reason why + type: string + enum: + - duplicate_declaration + nullable: true + example: duplicate_declaration + uplift_paid: + description: If participant is eligible for uplift, whether it has been + paid as part of this declaration + type: boolean + example: true + has_passed: + description: Whether the participant has failed or passed + type: string + example: true + nullable: true + lead_provider_name: + description: The name of the provider that submitted the declaration + type: string + nullable: false ParticipantDeclarationRequest: description: A participant declaration data request type: object diff --git a/spec/requests/api/docs/v3/declarations_spec.rb b/spec/requests/api/docs/v3/declarations_spec.rb index 1c9da8ed9c..f499b7e731 100644 --- a/spec/requests/api/docs/v3/declarations_spec.rb +++ b/spec/requests/api/docs/v3/declarations_spec.rb @@ -1,6 +1,64 @@ require "rails_helper" require "swagger_helper" -RSpec.describe "Participant Declarations endpoint", type: :request, openapi_spec: "v1/swagger.yaml" do +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 } + + 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" + 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: :v3) + 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/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 diff --git a/spec/swagger_schemas/filters/list_participant_declarations.rb b/spec/swagger_schemas/filters/list_participant_declarations.rb index fe99df9951..e5c94c577a 100644 --- a/spec/swagger_schemas/filters/list_participant_declarations.rb +++ b/spec/swagger_schemas/filters/list_participant_declarations.rb @@ -17,5 +17,17 @@ }, }.tap { |h| h[:v2] = h[:v1] - h[:v3] = h[:v1] + h[:v3] = h[:v1].deep_dup + h[:v3][:properties].merge!({ + cohort: { + description: "Return participant declarations associated to the specified cohort or cohorts. This is a comma delimited string of years.", + type: :string, + example: "2021,2022", + }, + delivery_partner_id: { + description: "Return participant declarations associated to the specified delivery partner or delivery partners. This is a comma delimited string of delivery partner IDs.", + type: :string, + example: "7e5bcdbf-c818-4961-8da5-439cab1984e0", + }, + }) }.freeze diff --git a/spec/swagger_schemas/models/participant_declaration.rb b/spec/swagger_schemas/models/participant_declaration.rb index dd94a41359..7a34af43a3 100644 --- a/spec/swagger_schemas/models/participant_declaration.rb +++ b/spec/swagger_schemas/models/participant_declaration.rb @@ -8,10 +8,23 @@ "$ref": "#/components/schemas/IDAttribute", }, type: { - description: "The data type", type: :string, + enum: %w[ + participant-declaration + ], + example: "participant-declaration", }, attributes: { + required: %w[ + participant_id + declaration_type + declaration_date + course_identifier + eligible_for_payment + voided + state + updated_at + ], properties: { participant_id: { description: "The unique identifier of this participant declaration record", @@ -110,93 +123,113 @@ }, v2: { description: "The data attributes associated with a participant declaration response", - type: :object, required: %i[id type attributes], - id: { - "$ref": "#/components/schemas/IDAttribute", - }, - type: { - description: "The data type", - type: :string, - }, - attributes: { - properties: { - participant_id: { - description: "The unique id of the participant", - type: :string, - format: :uuid, - example: "db3a7848-7308-4879-942a-c4a70ced400a", - }, - declaration_type: { - description: "The event declaration type", - type: :string, - enum: %w[ - started - retained-1 - retained-2 - retained-3 - retained-4 - completed - extended-1 - extended-2 - extended-3 - ], - example: "started", - }, - declaration_date: { - description: "The event declaration date", - type: :string, - format: "date-time", - example: "2021-05-31T02:21:32.000Z", - }, - course_identifier: { - description: "The type of course the participant is enrolled in", - type: :string, - enum: %w[ - npq-leading-teaching - npq-leading-behaviour-culture - npq-leading-teaching-development - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership - npq-additional-support-offer - npq-early-headship-coaching-offer - npq-leading-primary-mathematics - ], - example: "ecf-induction", - }, - state: { - description: "Indicates the state of this payment declaration", - type: :string, - enum: %w[ - submitted - eligible - payable - paid - voided - ineligible - ], - example: "submitted", - }, - updated_at: { - description: "The date the declaration was last updated", - type: :string, - format: "date-time", - example: "2021-05-31T02:22:32.000Z", - }, - has_passed: { - description: "Whether the participant has failed or passed", - type: :boolean, - example: true, - nullable: true, + properties: { + id: { + "$ref": "#/components/schemas/IDAttribute", + }, + type: { + type: :string, + enum: %w[ + participant-declaration + ], + example: "participant-declaration", + }, + attributes: { + required: %w[ + participant_id + declaration_type + declaration_date + course_identifier + state + updated_at + ], + properties: { + participant_id: { + description: "The unique identifier of this participant declaration record", + type: :string, + format: :uuid, + nullable: false, + example: "db3a7848-7308-4879-942a-c4a70ced400a", + }, + declaration_type: { + description: "The event declaration type", + type: :string, + nullable: false, + example: "started", + enum: %w[ + started + retained-1 + retained-2 + retained-3 + retained-4 + completed + extended-1 + extended-2 + extended-3 + ], + }, + declaration_date: { + description: "The event declaration date", + type: :string, + nullable: false, + example: "2022-04-30", + }, + course_identifier: { + description: "The NPQ course this NPQ application relates to", + type: :string, + nullable: false, + example: "npq-leading-teaching", + enum: %w[ + npq-leading-teaching + npq-leading-behaviour-culture + npq-leading-teaching-development + npq-leading-literacy + npq-senior-leadership + npq-headship + npq-executive-leadership + npq-early-years-leadership + npq-additional-support-offer + npq-early-headship-coaching-offer + npq-leading-primary-mathematics + npq-senco + ], + }, + state: { + description: "Indicates the state of this payment declaration", + type: :string, + nullable: false, + example: "submitted", + enum: %w[ + submitted + eligible + payable + paid + voided + ineligible + awaiting-clawback + clawed-back + ], + }, + updated_at: { + description: "The date the application was last updated", + type: :string, + nullable: false, + format: :"date-time", + example: "2021-05-31T02:22:32.000Z", + }, + has_passed: { + description: "The date the declaration was last updated", + type: :string, + nullable: true, + example: true, + }, }, }, }, }, v3: { - description: "The details of a participant declaration", + description: "The data attributes associated with a participant declaration response", type: :object, required: %i[id type attributes], properties: { @@ -204,11 +237,137 @@ "$ref": "#/components/schemas/IDAttribute", }, type: { - description: "The data type", type: :string, + enum: %w[ + participant-declaration + ], + example: "participant-declaration", }, attributes: { - - } + required: %w[ + participant_id + declaration_type + declaration_date + course_identifier + state + updated_at + lead_provider_name + ], + properties: { + participant_id: { + description: "The unique id of the participant", + type: "string", + format: "uuid", + example: "db3a7848-7308-4879-942a-c4a70ced400a", + }, + declaration_type: { + description: "The event declaration type", + type: "string", + enum: %w[ + started + retained-1 + retained-2 + retained-3 + retained-4 + completed + extended-1 + extended-2 + extended-3 + ], + example: "started", + }, + declaration_date: { + description: "The event declaration date", + type: "string", + format: "date-time", + example: "2021-05-31T02:21:32.000Z", + }, + course_identifier: { + description: "The type of course the participant is enrolled in", + type: "string", + enum: %w[ + npq-leading-teaching + npq-leading-behaviour-culture + npq-leading-teaching-development + npq-leading-literacy + npq-senior-leadership + npq-headship + npq-executive-leadership + npq-early-years-leadership + npq-additional-support-offer + npq-early-headship-coaching-offer + npq-leading-primary-mathematics + ], + example: "npq-leading-teaching", + }, + state: { + description: "Indicates the state of this payment declaration", + type: "string", + enum: %w[ + submitted + eligible + payable + paid + voided + ineligible + awaiting-clawback + clawed-back + ], + example: "submitted", + }, + updated_at: { + description: "The date the declaration was last updated", + type: "string", + format: "date-time", + example: "2021-05-31T02:22:32.000Z", + }, + created_at: { + description: "The date the declaration was created", + type: "string", + format: "date-time", + example: "2021-05-31T02:22:32.000Z", + }, + statement_id: { + description: "Unique ID of the statement the declaration will be paid as part of", + type: "string", + format: "uuid", + example: "cd3a12347-7308-4879-942a-c4a70ced400a", + nullable: true, + }, + clawback_statement_id: { + description: "Unique id of the statement to which the declaration will be clawed back on, if any", + type: "string", + format: "uuid", + example: "cd3a12347-7308-4879-942a-c4a70ced400a", + nullable: true, + }, + ineligible_for_funding_reason: { + description: "If the declaration is ineligible, the reason why", + type: "string", + enum: %w[ + duplicate_declaration + ], + nullable: true, + example: "duplicate_declaration", + }, + uplift_paid: { + description: "If participant is eligible for uplift, whether it has been paid as part of this declaration", + type: "boolean", + example: true, + }, + has_passed: { + description: "Whether the participant has failed or passed", + type: "string", # Need update when completed + example: true, + nullable: true, + }, + lead_provider_name: { + description: "The name of the provider that submitted the declaration", + type: "string", + nullable: false, + }, + }, + }, + }, }, }.freeze From 15c4e72c056c57c5c3248b6d40eba2ebfd151621 Mon Sep 17 00:00:00 2001 From: Pablo M Date: Fri, 5 Jul 2024 13:40:03 +0200 Subject: [PATCH 04/11] Remove `let`: not needed --- spec/requests/api/docs/v3/declarations_spec.rb | 3 --- 1 file changed, 3 deletions(-) diff --git a/spec/requests/api/docs/v3/declarations_spec.rb b/spec/requests/api/docs/v3/declarations_spec.rb index f499b7e731..a1a7f17515 100644 --- a/spec/requests/api/docs/v3/declarations_spec.rb +++ b/spec/requests/api/docs/v3/declarations_spec.rb @@ -40,9 +40,6 @@ 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: :v3) - end let(:invalid_attributes) { { participant_id: "invalid" } } let(:attributes) do { From caf0ad5435d7e6bb1c8a874374d2c482d6b1ae1a Mon Sep 17 00:00:00 2001 From: Pablo M Date: Fri, 5 Jul 2024 13:47:10 +0200 Subject: [PATCH 05/11] Remove delivery_partner_id from declarations v3 --- .../filters/list_participant_declarations.rb | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/spec/swagger_schemas/filters/list_participant_declarations.rb b/spec/swagger_schemas/filters/list_participant_declarations.rb index e5c94c577a..c00bdc77d0 100644 --- a/spec/swagger_schemas/filters/list_participant_declarations.rb +++ b/spec/swagger_schemas/filters/list_participant_declarations.rb @@ -23,11 +23,6 @@ description: "Return participant declarations associated to the specified cohort or cohorts. This is a comma delimited string of years.", type: :string, example: "2021,2022", - }, - delivery_partner_id: { - description: "Return participant declarations associated to the specified delivery partner or delivery partners. This is a comma delimited string of delivery partner IDs.", - type: :string, - example: "7e5bcdbf-c818-4961-8da5-439cab1984e0", - }, + } }) }.freeze From 7eae7bab93c6185384e62ce9e92c03e00b6cb594 Mon Sep 17 00:00:00 2001 From: Pablo M Date: Fri, 5 Jul 2024 14:46:41 +0200 Subject: [PATCH 06/11] DRy-up participant declaration --- public/api/docs/v3/swagger.yaml | 26 -- .../filters/list_participant_declarations.rb | 2 +- .../models/participant_declaration.rb | 342 +++--------------- 3 files changed, 57 insertions(+), 313 deletions(-) diff --git a/public/api/docs/v3/swagger.yaml b/public/api/docs/v3/swagger.yaml index d4365e324d..2010ac8e45 100644 --- a/public/api/docs/v3/swagger.yaml +++ b/public/api/docs/v3/swagger.yaml @@ -328,26 +328,6 @@ paths: description: The participant declaration being created content: application/json: - examples: - success: - value: - data: - id: d0b4a32e-a272-489e-b30a-cb17131457fc - type: participant-declaration - attributes: - participant_id: db3a7848-7308-4879-942a-c4a70ced400a - declaration_type: started - declaration_date: '2021-05-31T02:21:32.000Z' - course_identifier: npq-leading-teaching - state: submitted - updated_at: '2021-05-31T02:22:32.000Z' - created_at: '2021-05-31T02:22:32.000Z' - statement_id: cd3a12347-7308-4879-942a-c4a70ced400a - clawback_statement_id: cd3a12347-7308-4879-942a-c4a70ced400a - ineligible_for_funding_reason: duplicate_declaration - uplift_paid: true - has_passed: true - lead_provider_name: schema: "$ref": "#/components/schemas/ParticipantDeclarationResponse" '401': @@ -972,12 +952,6 @@ components: cohort or cohorts. This is a comma delimited string of years. type: string example: '2021,2022' - delivery_partner_id: - description: Return participant declarations associated to the specified - delivery partner or delivery partners. This is a comma delimited string - of delivery partner IDs. - type: string - example: 7e5bcdbf-c818-4961-8da5-439cab1984e0 ListStatementsFilter: description: Filter statements to return more specific results type: object diff --git a/spec/swagger_schemas/filters/list_participant_declarations.rb b/spec/swagger_schemas/filters/list_participant_declarations.rb index c00bdc77d0..26cf9db2c2 100644 --- a/spec/swagger_schemas/filters/list_participant_declarations.rb +++ b/spec/swagger_schemas/filters/list_participant_declarations.rb @@ -23,6 +23,6 @@ description: "Return participant declarations associated to the specified cohort or cohorts. This is a comma delimited string of years.", type: :string, example: "2021,2022", - } + }, }) }.freeze diff --git a/spec/swagger_schemas/models/participant_declaration.rb b/spec/swagger_schemas/models/participant_declaration.rb index 7a34af43a3..df25abb7a2 100644 --- a/spec/swagger_schemas/models/participant_declaration.rb +++ b/spec/swagger_schemas/models/participant_declaration.rb @@ -15,7 +15,7 @@ example: "participant-declaration", }, attributes: { - required: %w[ + required: %i[ participant_id declaration_type declaration_date @@ -38,17 +38,7 @@ type: :string, nullable: false, example: "started", - enum: %w[ - started - retained-1 - retained-2 - retained-3 - retained-4 - completed - extended-1 - extended-2 - extended-3 - ], + enum: Schedule::DECLARATION_TYPES, }, declaration_date: { description: "The event declaration date", @@ -60,21 +50,8 @@ description: "The NPQ course this NPQ application relates to", type: :string, nullable: false, - example: "npq-leading-teaching", - enum: %w[ - npq-leading-teaching - npq-leading-behaviour-culture - npq-leading-teaching-development - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership - npq-additional-support-offer - npq-early-headship-coaching-offer - npq-leading-primary-mathematics - npq-senco - ], + example: Course::IDENTIFIERS.first, + enum: Course::IDENTIFIERS, }, eligible_for_payment: { description: "[Deprecated - use state instead] Indicates whether this declaration would be eligible for funding from the DfE", @@ -93,16 +70,7 @@ type: :string, nullable: false, example: "submitted", - enum: %w[ - submitted - eligible - payable - paid - voided - ineligible - awaiting-clawback - clawed-back - ], + enum: Declaration.states.keys, }, updated_at: { description: "The date the application was last updated", @@ -112,114 +80,7 @@ example: "2021-05-31T02:22:32.000Z", }, has_passed: { - description: "The date the declaration was last updated", - type: :string, - nullable: true, - example: true, - }, - }, - }, - }, - }, - v2: { - description: "The data attributes associated with a participant declaration response", - required: %i[id type attributes], - properties: { - id: { - "$ref": "#/components/schemas/IDAttribute", - }, - type: { - type: :string, - enum: %w[ - participant-declaration - ], - example: "participant-declaration", - }, - attributes: { - required: %w[ - participant_id - declaration_type - declaration_date - course_identifier - state - updated_at - ], - properties: { - participant_id: { - description: "The unique identifier of this participant declaration record", - type: :string, - format: :uuid, - nullable: false, - example: "db3a7848-7308-4879-942a-c4a70ced400a", - }, - declaration_type: { - description: "The event declaration type", - type: :string, - nullable: false, - example: "started", - enum: %w[ - started - retained-1 - retained-2 - retained-3 - retained-4 - completed - extended-1 - extended-2 - extended-3 - ], - }, - declaration_date: { - description: "The event declaration date", - type: :string, - nullable: false, - example: "2022-04-30", - }, - course_identifier: { - description: "The NPQ course this NPQ application relates to", - type: :string, - nullable: false, - example: "npq-leading-teaching", - enum: %w[ - npq-leading-teaching - npq-leading-behaviour-culture - npq-leading-teaching-development - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership - npq-additional-support-offer - npq-early-headship-coaching-offer - npq-leading-primary-mathematics - npq-senco - ], - }, - state: { - description: "Indicates the state of this payment declaration", - type: :string, - nullable: false, - example: "submitted", - enum: %w[ - submitted - eligible - payable - paid - voided - ineligible - awaiting-clawback - clawed-back - ], - }, - updated_at: { - description: "The date the application was last updated", - type: :string, - nullable: false, - format: :"date-time", - example: "2021-05-31T02:22:32.000Z", - }, - has_passed: { - description: "The date the declaration was last updated", + description: "Whether the participant has failed or passed", type: :string, nullable: true, example: true, @@ -227,147 +88,56 @@ }, }, }, - }, - v3: { - description: "The data attributes associated with a participant declaration response", - type: :object, - required: %i[id type attributes], - properties: { - id: { - "$ref": "#/components/schemas/IDAttribute", - }, - type: { - type: :string, - enum: %w[ - participant-declaration - ], - example: "participant-declaration", - }, - attributes: { - required: %w[ - participant_id - declaration_type - declaration_date - course_identifier - state - updated_at - lead_provider_name - ], - properties: { - participant_id: { - description: "The unique id of the participant", - type: "string", - format: "uuid", - example: "db3a7848-7308-4879-942a-c4a70ced400a", - }, - declaration_type: { - description: "The event declaration type", - type: "string", - enum: %w[ - started - retained-1 - retained-2 - retained-3 - retained-4 - completed - extended-1 - extended-2 - extended-3 - ], - example: "started", - }, - declaration_date: { - description: "The event declaration date", - type: "string", - format: "date-time", - example: "2021-05-31T02:21:32.000Z", - }, - course_identifier: { - description: "The type of course the participant is enrolled in", - type: "string", - enum: %w[ - npq-leading-teaching - npq-leading-behaviour-culture - npq-leading-teaching-development - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership - npq-additional-support-offer - npq-early-headship-coaching-offer - npq-leading-primary-mathematics - ], - example: "npq-leading-teaching", - }, - state: { - description: "Indicates the state of this payment declaration", - type: "string", - enum: %w[ - submitted - eligible - payable - paid - voided - ineligible - awaiting-clawback - clawed-back - ], - example: "submitted", - }, - updated_at: { - description: "The date the declaration was last updated", - type: "string", - format: "date-time", - example: "2021-05-31T02:22:32.000Z", - }, - created_at: { - description: "The date the declaration was created", - type: "string", - format: "date-time", - example: "2021-05-31T02:22:32.000Z", - }, - statement_id: { - description: "Unique ID of the statement the declaration will be paid as part of", - type: "string", - format: "uuid", - example: "cd3a12347-7308-4879-942a-c4a70ced400a", - nullable: true, - }, - clawback_statement_id: { - description: "Unique id of the statement to which the declaration will be clawed back on, if any", - type: "string", - format: "uuid", - example: "cd3a12347-7308-4879-942a-c4a70ced400a", - nullable: true, - }, - ineligible_for_funding_reason: { - description: "If the declaration is ineligible, the reason why", - type: "string", - enum: %w[ + } +}.tap { |h| + h[:v2] = h[:v1].deep_dup + h[:v2][:properties][:attributes][:required] = h[:v1][:properties][:attributes][:required].excluding(:voided, :eligible_for_payment) + h[:v2][:properties][:attributes][:properties] = h[:v1][:properties][:attributes][:properties].excluding(:voided, :eligible_for_payment) + h[:v3] = h[:v2].deep_dup + h[:v3][:properties][:attributes][:properties][:statement_id] = { + description: "Unique ID of the statement the declaration will be paid as part of", + type: "string", + format: "uuid", + example: "cd3a12347-7308-4879-942a-c4a70ced400a", + nullable: true, + } + h[:v3][:properties][:attributes][:properties][:clawback_statement_id] = { + description: "Unique id of the statement to which the declaration will be clawed back on, if any", + type: "string", + format: "uuid", + example: "cd3a12347-7308-4879-942a-c4a70ced400a", + nullable: true, + } + h[:v3][:properties][:attributes][:properties][:ineligible_for_funding_reason] = { + description: "If the declaration is ineligible, the reason why", + type: "string", + enum: %w[ duplicate_declaration ], - nullable: true, - example: "duplicate_declaration", - }, - uplift_paid: { - description: "If participant is eligible for uplift, whether it has been paid as part of this declaration", - type: "boolean", - example: true, - }, - has_passed: { - description: "Whether the participant has failed or passed", - type: "string", # Need update when completed - example: true, - nullable: true, - }, - lead_provider_name: { - description: "The name of the provider that submitted the declaration", - type: "string", - nullable: false, - }, - }, - }, - }, - }, + nullable: true, + example: "duplicate_declaration", + } + h[:v3][:properties][:attributes][:properties][:uplift_paid] = { + description: "If participant is eligible for uplift, whether it has been paid as part of this declaration", + type: "boolean", + example: true, + } + h[:v3][:properties][:attributes][:properties][:has_passed] = { + description: "Whether the participant has failed or passed", + type: "string", # Need update when completed + example: true, + nullable: true, + } + h[:v3][:properties][:attributes][:properties][:lead_provider_name] = { + description: "The name of the provider that submitted the declaration", + type: "string", + nullable: false, + } + h[:v3][:properties][:attributes][:properties][:created_at] = { + description: "The date the application was created", + type: :string, + nullable: false, + format: :"date-time", + example: "2021-05-31T02:22:32.000Z", + } }.freeze From aae4d2f18f52f6a909c980abd591288216e2cbfa Mon Sep 17 00:00:00 2001 From: Pablo M Date: Fri, 5 Jul 2024 15:52:19 +0200 Subject: [PATCH 07/11] Update Swagger --- public/api/docs/v1/swagger.yaml | 447 ++++++++++++++++++++++++++++++++ public/api/docs/v2/swagger.yaml | 306 +++++++++++++++++++++- public/api/docs/v3/swagger.yaml | 63 ++--- 3 files changed, 771 insertions(+), 45 deletions(-) diff --git a/public/api/docs/v1/swagger.yaml b/public/api/docs/v1/swagger.yaml index fc3f7b9c03..fdd750d753 100644 --- a/public/api/docs/v1/swagger.yaml +++ b/public/api/docs/v1/swagger.yaml @@ -319,6 +319,154 @@ paths: text/csv: schema: "$ref": "#/components/schemas/UnauthorisedResponse" + "/api/v1/participant-declarations": + get: + summary: Retrieve multiple Participant declarations + tags: + - Participant declarations + security: + - api_key: [] + parameters: + - name: filter + in: query + required: false + schema: + "$ref": "#/components/schemas/ListParticipantDeclarationsFilter" + - name: page + in: query + required: false + schema: + "$ref": "#/components/schemas/PaginationFilter" + responses: + '200': + description: A list of Participant declarations + content: + application/json: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationsResponse" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/UnauthorisedResponse" + post: + summary: Declare a participant has reached a milestone + tags: + - Participant declarations + security: + - api_key: [] + parameters: [] + responses: + '200': + description: The participant declaration being created + content: + application/json: + examples: + success: + value: + data: + id: d0b4a32e-a272-489e-b30a-cb17131457fc + type: participant-declaration + attributes: + participant_id: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: started + declaration_date: '2022-04-30' + course_identifier: npq-senior-leadership + eligible_for_payment: true + voided: true + state: submitted + updated_at: '2021-05-31T02:22:32.000Z' + has_passed: true + schema: + "$ref": "#/components/schemas/ParticipantDeclarationResponse" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/UnauthorisedResponse" + '400': + description: Bad request + content: + application/json: + schema: + "$ref": "#/components/schemas/BadRequestResponse" + '422': + description: Unprocessable entity + content: + application/json: + schema: + "$ref": "#/components/schemas/UnprocessableEntityResponse" + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationRequest" + "/api/v1/participant-declarations/{id}": + get: + summary: Retrieve a single Participant declarations + tags: + - Participant declarations + security: + - api_key: [] + parameters: + - name: id + in: path + required: true + schema: + "$ref": "#/components/schemas/IDAttribute" + responses: + '200': + description: A single Participant declarations + content: + application/json: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationResponse" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/UnauthorisedResponse" + '404': + description: Not found + content: + application/json: + schema: + "$ref": "#/components/schemas/NotFoundResponse" + "/api/v1/participant-declarations/{id}/void": + put: + summary: Void a declaration + tags: + - Participant declarations + security: + - api_key: [] + parameters: + - name: id + in: path + required: true + schema: + "$ref": "#/components/schemas/IDAttribute" + responses: + '200': + description: The participant declaration being voided + content: + application/json: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationResponse" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/UnauthorisedResponse" + '404': + description: Not found + content: + application/json: + schema: + "$ref": "#/components/schemas/NotFoundResponse" "/api/v1/participants/npq": get: summary: Retrieve multiple NPQ participants @@ -647,6 +795,19 @@ components: and time (ISO 8601 date format). type: string example: '2021-05-13T11:21:55Z' + ListParticipantDeclarationsFilter: + description: Refine participant declarations to return. + type: object + properties: + participant_id: + description: The unique id of the participant + type: string + example: 7e5bcdbf-c818-4961-8da5-439cab1984e0 + updated_since: + description: Return only records that have been updated since this date + and time (ISO 8601 date format). + type: string + example: '2021-05-13T11:21:55Z' UnauthorisedResponse: description: Authorization information is missing or invalid. type: object @@ -1676,3 +1837,289 @@ components: nullable: true type: string example: '2023' + ParticipantDeclaration: + description: The details of a participant declaration + type: object + required: + - id + - type + - attributes + properties: + id: + "$ref": "#/components/schemas/IDAttribute" + type: + type: string + enum: + - participant-declaration + example: participant-declaration + attributes: + required: + - participant_id + - declaration_type + - declaration_date + - course_identifier + - eligible_for_payment + - voided + - state + - updated_at + properties: + participant_id: + description: The unique identifier of this participant declaration record + type: string + format: uuid + nullable: false + example: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: + description: The event declaration type + type: string + nullable: false + example: started + enum: + - started + - retained-1 + - retained-2 + - completed + declaration_date: + description: The event declaration date + type: string + nullable: false + example: '2022-04-30' + course_identifier: + description: The NPQ course this NPQ application relates to + type: string + nullable: false + example: npq-senior-leadership + enum: + - npq-senior-leadership + - npq-headship + - npq-executive-leadership + - npq-early-years-leadership + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-leading-primary-mathematics + - npq-additional-support-offer + - npq-early-headship-coaching-offer + - npq-senco + eligible_for_payment: + description: "[Deprecated - use state instead] Indicates whether this + declaration would be eligible for funding from the DfE" + type: boolean + nullable: true + example: true + voided: + description: "[Deprecated - use state instead] Indicates whether this + declaration has been voided" + type: boolean + nullable: true + example: true + state: + description: Indicates the state of this payment declaration + type: string + nullable: false + example: submitted + enum: + - submitted + - eligible + - payable + - paid + - voided + - ineligible + - awaiting_clawback + - clawed_back + updated_at: + description: The date the application was last updated + type: string + nullable: false + format: date-time + example: '2021-05-31T02:22:32.000Z' + has_passed: + description: Whether the participant has failed or passed + type: string + nullable: true + example: true + ParticipantDeclarationRequest: + description: A participant declaration data request + type: object + properties: + type: + type: string + enum: + - participant-declaration + example: participant-declaration + attributes: + anyOf: + - "$ref": "#/components/schemas/ParticipantDeclarationStartedRequest" + - "$ref": "#/components/schemas/ParticipantDeclarationRetainedRequest" + - "$ref": "#/components/schemas/ParticipantDeclarationCompletedRequest" + ParticipantDeclarationResponse: + description: A single participant declaration. + type: object + required: + - data + properties: + data: + "$ref": "#/components/schemas/ParticipantDeclaration" + ParticipantDeclarationsResponse: + description: A list of participant declarations. + type: object + required: + - data + properties: + data: + type: array + items: + "$ref": "#/components/schemas/ParticipantDeclaration" + ParticipantDeclarationStartedRequest: + description: An NPQ started participant declaration + type: object + additionalProperties: false + properties: + participant_id: + description: The unique id of the participant + type: string + format: uuid + example: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: + description: The event declaration type + type: string + enum: + - started + example: started + declaration_date: + description: The event declaration date + type: string + format: date-time + example: '2021-05-31T02:21:32.000Z' + course_identifier: + description: The type of course the participant is enrolled in + type: string + enum: + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-senior-leadership + - npq-headship + - npq-executive-leadership + - npq-early-years-leadership + - npq-additional-support-offer + - npq-early-headship-coaching-offer + - npq-leading-primary-mathematics + - npq-senco + example: npq-headship + required: + - participant_id + - declaration_type + - declaration_date + - course_identifier + example: + participant_id: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: started + declaration_date: '2021-05-31T02:21:32.000Z' + course_identifier: npq-leading-teaching + ParticipantDeclarationRetainedRequest: + description: An NPQ participant retained declaration + type: object + additionalProperties: false + properties: + participant_id: + description: The unique id of the participant + type: string + format: uuid + example: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: + description: The event declaration type + type: string + enum: + - retained-1 + - retained-2 + example: retained-1 + declaration_date: + description: The event declaration date + type: string + format: date-time + example: '2021-05-31T02:21:32.000Z' + course_identifier: + description: The type of course the participant is enrolled in + type: string + enum: + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-senior-leadership + - npq-headship + - npq-executive-leadership + - npq-early-years-leadership + - npq-additional-support-offer + - npq-early-headship-coaching-offer + - npq-leading-primary-mathematics + - npq-senco + example: npq-headship + required: + - participant_id + - declaration_type + - declaration_date + - course_identifier + example: + participant_id: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: retained-1 + declaration_date: '2021-05-31T02:21:32.000Z' + course_identifier: npq-headship + ParticipantDeclarationCompletedRequest: + description: An NPQ completed participant declaration + type: object + required: + - participant_id + - declaration_type + - declaration_date + - course_identifier + - has_passed + additionalProperties: false + properties: + participant_id: + description: The unique id of the participant + type: string + format: uuid + example: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: + description: The event declaration type + type: string + enum: + - completed + example: completed + declaration_date: + description: The event declaration date + type: string + format: date-time + example: '2021-05-31T02:21:32.000Z' + course_identifier: + description: The type of course the participant is enrolled in + type: string + enum: + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-senior-leadership + - npq-headship + - npq-executive-leadership + - npq-early-years-leadership + - npq-additional-support-offer + - npq-early-headship-coaching-offer + - npq-leading-primary-mathematics + - npq-senco + example: npq-headship + has_passed: + description: Whether the participant has failed or passed + type: boolean + example: true + nullable: true + example: + participant_id: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: completed + declaration_date: '2021-05-31T02:21:32.000Z' + course_identifier: npq-leading-teaching + has_passed: true diff --git a/public/api/docs/v2/swagger.yaml b/public/api/docs/v2/swagger.yaml index 5adbbf132a..251af658d9 100644 --- a/public/api/docs/v2/swagger.yaml +++ b/public/api/docs/v2/swagger.yaml @@ -367,22 +367,15 @@ paths: value: data: id: d0b4a32e-a272-489e-b30a-cb17131457fc - type: npq-participant + type: participant-declaration attributes: - email: isabelle.macdonald2@some-school.example.com - full_name: Isabelle MacDonald - teacher_reference_number: '1234567' + participant_id: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: started + declaration_date: '2022-04-30' + course_identifier: npq-senior-leadership + state: submitted updated_at: '2021-05-31T02:22:32.000Z' - npq_enrolments: - - course_identifier: npq-leading-teaching - schedule_identifier: npq-leadership-spring - cohort: '2022' - eligible_for_funding: true - npq_application_id: db3a7848-7308-4879-942a-c4a70ced400a - training_status: active - school_urn: '106286' - targeted_delivery_funding_eligibility: true - funded_place: true + has_passed: true schema: "$ref": "#/components/schemas/ParticipantDeclarationResponse" '401': @@ -901,6 +894,19 @@ components: and time (ISO 8601 date format). type: string example: '2021-05-13T11:21:55Z' + ListParticipantDeclarationsFilter: + description: Refine participant declarations to return. + type: object + properties: + participant_id: + description: The unique id of the participant + type: string + example: 7e5bcdbf-c818-4961-8da5-439cab1984e0 + updated_since: + description: Return only records that have been updated since this date + and time (ISO 8601 date format). + type: string + example: '2021-05-13T11:21:55Z' UnauthorisedResponse: description: Authorization information is missing or invalid. type: object @@ -2046,3 +2052,275 @@ components: nullable: true type: string example: '2023' + ParticipantDeclaration: + description: The details of a participant declaration + type: object + required: + - id + - type + - attributes + properties: + id: + "$ref": "#/components/schemas/IDAttribute" + type: + type: string + enum: + - participant-declaration + example: participant-declaration + attributes: + required: + - participant_id + - declaration_type + - declaration_date + - course_identifier + - state + - updated_at + properties: + participant_id: + description: The unique identifier of this participant declaration record + type: string + format: uuid + nullable: false + example: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: + description: The event declaration type + type: string + nullable: false + example: started + enum: + - started + - retained-1 + - retained-2 + - completed + declaration_date: + description: The event declaration date + type: string + nullable: false + example: '2022-04-30' + course_identifier: + description: The NPQ course this NPQ application relates to + type: string + nullable: false + example: npq-senior-leadership + enum: + - npq-senior-leadership + - npq-headship + - npq-executive-leadership + - npq-early-years-leadership + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-leading-primary-mathematics + - npq-additional-support-offer + - npq-early-headship-coaching-offer + - npq-senco + state: + description: Indicates the state of this payment declaration + type: string + nullable: false + example: submitted + enum: + - submitted + - eligible + - payable + - paid + - voided + - ineligible + - awaiting_clawback + - clawed_back + updated_at: + description: The date the application was last updated + type: string + nullable: false + format: date-time + example: '2021-05-31T02:22:32.000Z' + has_passed: + description: Whether the participant has failed or passed + type: string + nullable: true + example: true + ParticipantDeclarationRequest: + description: A participant declaration data request + type: object + properties: + type: + type: string + enum: + - participant-declaration + example: participant-declaration + attributes: + anyOf: + - "$ref": "#/components/schemas/ParticipantDeclarationStartedRequest" + - "$ref": "#/components/schemas/ParticipantDeclarationRetainedRequest" + - "$ref": "#/components/schemas/ParticipantDeclarationCompletedRequest" + ParticipantDeclarationResponse: + description: A single participant declaration. + type: object + required: + - data + properties: + data: + "$ref": "#/components/schemas/ParticipantDeclaration" + ParticipantDeclarationsResponse: + description: A list of participant declarations. + type: object + required: + - data + properties: + data: + type: array + items: + "$ref": "#/components/schemas/ParticipantDeclaration" + ParticipantDeclarationStartedRequest: + description: An NPQ started participant declaration + type: object + additionalProperties: false + properties: + participant_id: + description: The unique id of the participant + type: string + format: uuid + example: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: + description: The event declaration type + type: string + enum: + - started + example: started + declaration_date: + description: The event declaration date + type: string + format: date-time + example: '2021-05-31T02:21:32.000Z' + course_identifier: + description: The type of course the participant is enrolled in + type: string + enum: + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-senior-leadership + - npq-headship + - npq-executive-leadership + - npq-early-years-leadership + - npq-additional-support-offer + - npq-early-headship-coaching-offer + - npq-leading-primary-mathematics + - npq-senco + example: npq-headship + required: + - participant_id + - declaration_type + - declaration_date + - course_identifier + example: + participant_id: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: started + declaration_date: '2021-05-31T02:21:32.000Z' + course_identifier: npq-leading-teaching + ParticipantDeclarationRetainedRequest: + description: An NPQ participant retained declaration + type: object + additionalProperties: false + properties: + participant_id: + description: The unique id of the participant + type: string + format: uuid + example: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: + description: The event declaration type + type: string + enum: + - retained-1 + - retained-2 + example: retained-1 + declaration_date: + description: The event declaration date + type: string + format: date-time + example: '2021-05-31T02:21:32.000Z' + course_identifier: + description: The type of course the participant is enrolled in + type: string + enum: + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-senior-leadership + - npq-headship + - npq-executive-leadership + - npq-early-years-leadership + - npq-additional-support-offer + - npq-early-headship-coaching-offer + - npq-leading-primary-mathematics + - npq-senco + example: npq-headship + required: + - participant_id + - declaration_type + - declaration_date + - course_identifier + example: + participant_id: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: retained-1 + declaration_date: '2021-05-31T02:21:32.000Z' + course_identifier: npq-headship + ParticipantDeclarationCompletedRequest: + description: An NPQ completed participant declaration + type: object + required: + - participant_id + - declaration_type + - declaration_date + - course_identifier + - has_passed + additionalProperties: false + properties: + participant_id: + description: The unique id of the participant + type: string + format: uuid + example: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: + description: The event declaration type + type: string + enum: + - completed + example: completed + declaration_date: + description: The event declaration date + type: string + format: date-time + example: '2021-05-31T02:21:32.000Z' + course_identifier: + description: The type of course the participant is enrolled in + type: string + enum: + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-senior-leadership + - npq-headship + - npq-executive-leadership + - npq-early-years-leadership + - npq-additional-support-offer + - npq-early-headship-coaching-offer + - npq-leading-primary-mathematics + - npq-senco + example: npq-headship + has_passed: + description: Whether the participant has failed or passed + type: boolean + example: true + nullable: true + example: + participant_id: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: completed + declaration_date: '2021-05-31T02:21:32.000Z' + course_identifier: npq-leading-teaching + has_passed: true diff --git a/public/api/docs/v3/swagger.yaml b/public/api/docs/v3/swagger.yaml index 2010ac8e45..305d055275 100644 --- a/public/api/docs/v3/swagger.yaml +++ b/public/api/docs/v3/swagger.yaml @@ -1921,7 +1921,7 @@ components: - updated_at - "-updated_at" ParticipantDeclaration: - description: The data attributes associated with a participant declaration response + description: The details of a participant declaration type: object required: - id @@ -1943,51 +1943,51 @@ components: - course_identifier - state - updated_at - - lead_provider_name properties: participant_id: - description: The unique id of the participant + description: The unique identifier of this participant declaration record type: string format: uuid + nullable: false example: db3a7848-7308-4879-942a-c4a70ced400a declaration_type: description: The event declaration type type: string + nullable: false + example: started enum: - started - retained-1 - retained-2 - - retained-3 - - retained-4 - completed - - extended-1 - - extended-2 - - extended-3 - example: started declaration_date: description: The event declaration date type: string - format: date-time - example: '2021-05-31T02:21:32.000Z' + nullable: false + example: '2022-04-30' course_identifier: - description: The type of course the participant is enrolled in + description: The NPQ course this NPQ application relates to type: string + nullable: false + example: npq-senior-leadership enum: - - npq-leading-teaching - - npq-leading-behaviour-culture - - npq-leading-teaching-development - - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-leading-primary-mathematics - npq-additional-support-offer - npq-early-headship-coaching-offer - - npq-leading-primary-mathematics - example: npq-leading-teaching + - npq-senco state: description: Indicates the state of this payment declaration type: string + nullable: false + example: submitted enum: - submitted - eligible @@ -1995,19 +1995,19 @@ components: - paid - voided - ineligible - - awaiting-clawback - - clawed-back - example: submitted + - awaiting_clawback + - clawed_back updated_at: - description: The date the declaration was last updated + description: The date the application was last updated type: string + nullable: false format: date-time example: '2021-05-31T02:22:32.000Z' - created_at: - description: The date the declaration was created + has_passed: + description: Whether the participant has failed or passed type: string - format: date-time - example: '2021-05-31T02:22:32.000Z' + example: true + nullable: true statement_id: description: Unique ID of the statement the declaration will be paid as part of @@ -2034,15 +2034,16 @@ components: paid as part of this declaration type: boolean example: true - has_passed: - description: Whether the participant has failed or passed - type: string - example: true - nullable: true lead_provider_name: description: The name of the provider that submitted the declaration type: string nullable: false + created_at: + description: The date the application was created + type: string + nullable: false + format: date-time + example: '2021-05-31T02:22:32.000Z' ParticipantDeclarationRequest: description: A participant declaration data request type: object From cd7af638b7403692c33b14cd8a6913f68015fbeb Mon Sep 17 00:00:00 2001 From: Mooktakim Ahmed Date: Mon, 8 Jul 2024 10:49:26 +0100 Subject: [PATCH 08/11] [CPDLP-3103] rubocop fix --- .../models/participant_declaration.rb | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/spec/swagger_schemas/models/participant_declaration.rb b/spec/swagger_schemas/models/participant_declaration.rb index df25abb7a2..e60be9a896 100644 --- a/spec/swagger_schemas/models/participant_declaration.rb +++ b/spec/swagger_schemas/models/participant_declaration.rb @@ -88,7 +88,7 @@ }, }, }, - } + }, }.tap { |h| h[:v2] = h[:v1].deep_dup h[:v2][:properties][:attributes][:required] = h[:v1][:properties][:attributes][:required].excluding(:voided, :eligible_for_payment) @@ -112,8 +112,8 @@ description: "If the declaration is ineligible, the reason why", type: "string", enum: %w[ - duplicate_declaration - ], + duplicate_declaration + ], nullable: true, example: "duplicate_declaration", } @@ -134,10 +134,10 @@ nullable: false, } h[:v3][:properties][:attributes][:properties][:created_at] = { - description: "The date the application was created", - type: :string, - nullable: false, - format: :"date-time", - example: "2021-05-31T02:22:32.000Z", + description: "The date the application was created", + type: :string, + nullable: false, + format: :"date-time", + example: "2021-05-31T02:22:32.000Z", } }.freeze From 12ac0f72e7eeda0efcec142b707daf481dcead0b Mon Sep 17 00:00:00 2001 From: Mooktakim Ahmed Date: Mon, 8 Jul 2024 16:01:35 +0100 Subject: [PATCH 09/11] [CPDLP-3103] api version fix --- spec/requests/api/docs/v1/declarations_spec.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/requests/api/docs/v1/declarations_spec.rb b/spec/requests/api/docs/v1/declarations_spec.rb index 6231ca13d1..bc31dfd132 100644 --- a/spec/requests/api/docs/v1/declarations_spec.rb +++ b/spec/requests/api/docs/v1/declarations_spec.rb @@ -5,7 +5,7 @@ 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" From d7a7c2ae76c115db8e66b8cef7c7bc242281558e Mon Sep 17 00:00:00 2001 From: Mooktakim Ahmed Date: Mon, 8 Jul 2024 16:02:59 +0100 Subject: [PATCH 10/11] [CPDLP-3103] set required to each individual attribute --- public/api/docs/v1/swagger.yaml | 11 ++++++++++- public/api/docs/v2/swagger.yaml | 9 +++++++++ public/api/docs/v3/swagger.yaml | 9 +++++++++ .../requests/participant_declaration_request.rb | 3 +++ .../participant_declaration_started_request.rb | 4 ++++ 5 files changed, 35 insertions(+), 1 deletion(-) diff --git a/public/api/docs/v1/swagger.yaml b/public/api/docs/v1/swagger.yaml index fdd750d753..937a1e97ab 100644 --- a/public/api/docs/v1/swagger.yaml +++ b/public/api/docs/v1/swagger.yaml @@ -299,7 +299,7 @@ paths: schema: "$ref": "#/components/schemas/ApplicationChangeFundedPlaceRequest" required: true - "/api/v2/participant-declarations.csv": + "/api/v1/participant-declarations.csv": get: summary: Retrieve all Participant declarations in CSV format tags: @@ -1942,13 +1942,18 @@ components: ParticipantDeclarationRequest: description: A participant declaration data request type: object + required: + - type + - attributes properties: type: type: string + required: true enum: - participant-declaration example: participant-declaration attributes: + required: true anyOf: - "$ref": "#/components/schemas/ParticipantDeclarationStartedRequest" - "$ref": "#/components/schemas/ParticipantDeclarationRetainedRequest" @@ -1980,21 +1985,25 @@ components: description: The unique id of the participant type: string format: uuid + required: true example: db3a7848-7308-4879-942a-c4a70ced400a declaration_type: description: The event declaration type type: string + required: true enum: - started example: started declaration_date: description: The event declaration date type: string + required: true format: date-time example: '2021-05-31T02:21:32.000Z' course_identifier: description: The type of course the participant is enrolled in type: string + required: true enum: - npq-leading-teaching - npq-leading-behaviour-culture diff --git a/public/api/docs/v2/swagger.yaml b/public/api/docs/v2/swagger.yaml index 251af658d9..bd7ae2a42f 100644 --- a/public/api/docs/v2/swagger.yaml +++ b/public/api/docs/v2/swagger.yaml @@ -2143,13 +2143,18 @@ components: ParticipantDeclarationRequest: description: A participant declaration data request type: object + required: + - type + - attributes properties: type: type: string + required: true enum: - participant-declaration example: participant-declaration attributes: + required: true anyOf: - "$ref": "#/components/schemas/ParticipantDeclarationStartedRequest" - "$ref": "#/components/schemas/ParticipantDeclarationRetainedRequest" @@ -2181,21 +2186,25 @@ components: description: The unique id of the participant type: string format: uuid + required: true example: db3a7848-7308-4879-942a-c4a70ced400a declaration_type: description: The event declaration type type: string + required: true enum: - started example: started declaration_date: description: The event declaration date type: string + required: true format: date-time example: '2021-05-31T02:21:32.000Z' course_identifier: description: The type of course the participant is enrolled in type: string + required: true enum: - npq-leading-teaching - npq-leading-behaviour-culture diff --git a/public/api/docs/v3/swagger.yaml b/public/api/docs/v3/swagger.yaml index 305d055275..cd19c1afe3 100644 --- a/public/api/docs/v3/swagger.yaml +++ b/public/api/docs/v3/swagger.yaml @@ -2047,13 +2047,18 @@ components: ParticipantDeclarationRequest: description: A participant declaration data request type: object + required: + - type + - attributes properties: type: type: string + required: true enum: - participant-declaration example: participant-declaration attributes: + required: true anyOf: - "$ref": "#/components/schemas/ParticipantDeclarationStartedRequest" - "$ref": "#/components/schemas/ParticipantDeclarationRetainedRequest" @@ -2085,21 +2090,25 @@ components: description: The unique id of the participant type: string format: uuid + required: true example: db3a7848-7308-4879-942a-c4a70ced400a declaration_type: description: The event declaration type type: string + required: true enum: - started example: started declaration_date: description: The event declaration date type: string + required: true format: date-time example: '2021-05-31T02:21:32.000Z' course_identifier: description: The type of course the participant is enrolled in type: string + required: true enum: - npq-leading-teaching - npq-leading-behaviour-culture diff --git a/spec/swagger_schemas/requests/participant_declaration_request.rb b/spec/swagger_schemas/requests/participant_declaration_request.rb index 76cb809a7c..ed6529de86 100644 --- a/spec/swagger_schemas/requests/participant_declaration_request.rb +++ b/spec/swagger_schemas/requests/participant_declaration_request.rb @@ -1,15 +1,18 @@ PARTICIPANT_DECLARATION_REQUEST = { description: "A participant declaration data request", type: :object, + required: %w[type attributes], properties: { type: { type: :string, + required: true, enum: %w[ participant-declaration ], example: "participant-declaration", }, attributes: { + required: true, anyOf: [ { "$ref": "#/components/schemas/ParticipantDeclarationStartedRequest" }, { "$ref": "#/components/schemas/ParticipantDeclarationRetainedRequest" }, diff --git a/spec/swagger_schemas/requests/participant_declaration_started_request.rb b/spec/swagger_schemas/requests/participant_declaration_started_request.rb index 956f601d1a..8b64bb1ddc 100644 --- a/spec/swagger_schemas/requests/participant_declaration_started_request.rb +++ b/spec/swagger_schemas/requests/participant_declaration_started_request.rb @@ -7,11 +7,13 @@ description: "The unique id of the participant", type: :string, format: :uuid, + required: true, example: "db3a7848-7308-4879-942a-c4a70ced400a", }, declaration_type: { description: "The event declaration type", type: :string, + required: true, enum: %w[ started ], @@ -20,12 +22,14 @@ declaration_date: { description: "The event declaration date", type: :string, + required: true, format: "date-time", example: "2021-05-31T02:21:32.000Z", }, course_identifier: { description: "The type of course the participant is enrolled in", type: :string, + required: true, enum: %w[ npq-leading-teaching npq-leading-behaviour-culture From 82b37922c1841a870b9ed8e39b569a1154e4e6f5 Mon Sep 17 00:00:00 2001 From: Mooktakim Ahmed Date: Tue, 9 Jul 2024 17:27:45 +0100 Subject: [PATCH 11/11] [CPDLP-3103] make sure enums are set with variables, examples are set correctly for void --- public/api/docs/v1/swagger.yaml | 66 ++++++++++++------- public/api/docs/v2/swagger.yaml | 60 ++++++++++------- public/api/docs/v3/swagger.yaml | 65 +++++++++++------- .../requests/api/docs/v1/declarations_spec.rb | 13 +++- .../requests/api/docs/v2/declarations_spec.rb | 12 +++- .../requests/api/docs/v3/declarations_spec.rb | 12 +++- .../models/participant_declaration.rb | 7 +- ...rticipant_declaration_completed_request.rb | 19 +----- ...articipant_declaration_retained_request.rb | 19 +----- ...participant_declaration_started_request.rb | 19 +----- 10 files changed, 168 insertions(+), 124 deletions(-) diff --git a/public/api/docs/v1/swagger.yaml b/public/api/docs/v1/swagger.yaml index 937a1e97ab..94656c1c89 100644 --- a/public/api/docs/v1/swagger.yaml +++ b/public/api/docs/v1/swagger.yaml @@ -374,10 +374,10 @@ paths: declaration_date: '2022-04-30' course_identifier: npq-senior-leadership eligible_for_payment: true - voided: true + voided: false state: submitted updated_at: '2021-05-31T02:22:32.000Z' - has_passed: true + has_passed: schema: "$ref": "#/components/schemas/ParticipantDeclarationResponse" '401': @@ -453,6 +453,22 @@ paths: description: The participant declaration being voided content: application/json: + examples: + success: + value: + data: + id: d0b4a32e-a272-489e-b30a-cb17131457fc + type: participant-declaration + attributes: + participant_id: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: started + declaration_date: '2022-04-30' + course_identifier: npq-senior-leadership + eligible_for_payment: true + voided: true + state: voided + updated_at: '2021-05-31T02:22:32.000Z' + has_passed: schema: "$ref": "#/components/schemas/ParticipantDeclarationResponse" '401': @@ -1913,7 +1929,7 @@ components: declaration has been voided" type: boolean nullable: true - example: true + example: false state: description: Indicates the state of this payment declaration type: string @@ -1938,7 +1954,7 @@ components: description: Whether the participant has failed or passed type: string nullable: true - example: true + example: ParticipantDeclarationRequest: description: A participant declaration data request type: object @@ -2005,19 +2021,19 @@ components: type: string required: true enum: - - npq-leading-teaching - - npq-leading-behaviour-culture - - npq-leading-teaching-development - - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-leading-primary-mathematics - npq-additional-support-offer - npq-early-headship-coaching-offer - - npq-leading-primary-mathematics - npq-senco - example: npq-headship + example: npq-senior-leadership required: - participant_id - declaration_type @@ -2027,7 +2043,7 @@ components: participant_id: db3a7848-7308-4879-942a-c4a70ced400a declaration_type: started declaration_date: '2021-05-31T02:21:32.000Z' - course_identifier: npq-leading-teaching + course_identifier: npq-senior-leadership ParticipantDeclarationRetainedRequest: description: An NPQ participant retained declaration type: object @@ -2054,19 +2070,19 @@ components: description: The type of course the participant is enrolled in type: string enum: - - npq-leading-teaching - - npq-leading-behaviour-culture - - npq-leading-teaching-development - - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-leading-primary-mathematics - npq-additional-support-offer - npq-early-headship-coaching-offer - - npq-leading-primary-mathematics - npq-senco - example: npq-headship + example: npq-senior-leadership required: - participant_id - declaration_type @@ -2076,7 +2092,7 @@ components: participant_id: db3a7848-7308-4879-942a-c4a70ced400a declaration_type: retained-1 declaration_date: '2021-05-31T02:21:32.000Z' - course_identifier: npq-headship + course_identifier: npq-senior-leadership ParticipantDeclarationCompletedRequest: description: An NPQ completed participant declaration type: object @@ -2108,19 +2124,19 @@ components: description: The type of course the participant is enrolled in type: string enum: - - npq-leading-teaching - - npq-leading-behaviour-culture - - npq-leading-teaching-development - - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-leading-primary-mathematics - npq-additional-support-offer - npq-early-headship-coaching-offer - - npq-leading-primary-mathematics - npq-senco - example: npq-headship + example: npq-senior-leadership has_passed: description: Whether the participant has failed or passed type: boolean @@ -2130,5 +2146,5 @@ components: participant_id: db3a7848-7308-4879-942a-c4a70ced400a declaration_type: completed declaration_date: '2021-05-31T02:21:32.000Z' - course_identifier: npq-leading-teaching + course_identifier: npq-senior-leadership has_passed: true diff --git a/public/api/docs/v2/swagger.yaml b/public/api/docs/v2/swagger.yaml index bd7ae2a42f..73456c3851 100644 --- a/public/api/docs/v2/swagger.yaml +++ b/public/api/docs/v2/swagger.yaml @@ -375,7 +375,7 @@ paths: course_identifier: npq-senior-leadership state: submitted updated_at: '2021-05-31T02:22:32.000Z' - has_passed: true + has_passed: schema: "$ref": "#/components/schemas/ParticipantDeclarationResponse" '401': @@ -451,6 +451,20 @@ paths: description: The participant declaration being voided content: application/json: + examples: + success: + value: + data: + id: d0b4a32e-a272-489e-b30a-cb17131457fc + type: participant-declaration + attributes: + participant_id: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: started + declaration_date: '2022-04-30' + course_identifier: npq-senior-leadership + state: voided + updated_at: '2021-05-31T02:22:32.000Z' + has_passed: schema: "$ref": "#/components/schemas/ParticipantDeclarationResponse" '401': @@ -2139,7 +2153,7 @@ components: description: Whether the participant has failed or passed type: string nullable: true - example: true + example: ParticipantDeclarationRequest: description: A participant declaration data request type: object @@ -2206,19 +2220,19 @@ components: type: string required: true enum: - - npq-leading-teaching - - npq-leading-behaviour-culture - - npq-leading-teaching-development - - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-leading-primary-mathematics - npq-additional-support-offer - npq-early-headship-coaching-offer - - npq-leading-primary-mathematics - npq-senco - example: npq-headship + example: npq-senior-leadership required: - participant_id - declaration_type @@ -2228,7 +2242,7 @@ components: participant_id: db3a7848-7308-4879-942a-c4a70ced400a declaration_type: started declaration_date: '2021-05-31T02:21:32.000Z' - course_identifier: npq-leading-teaching + course_identifier: npq-senior-leadership ParticipantDeclarationRetainedRequest: description: An NPQ participant retained declaration type: object @@ -2255,19 +2269,19 @@ components: description: The type of course the participant is enrolled in type: string enum: - - npq-leading-teaching - - npq-leading-behaviour-culture - - npq-leading-teaching-development - - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-leading-primary-mathematics - npq-additional-support-offer - npq-early-headship-coaching-offer - - npq-leading-primary-mathematics - npq-senco - example: npq-headship + example: npq-senior-leadership required: - participant_id - declaration_type @@ -2277,7 +2291,7 @@ components: participant_id: db3a7848-7308-4879-942a-c4a70ced400a declaration_type: retained-1 declaration_date: '2021-05-31T02:21:32.000Z' - course_identifier: npq-headship + course_identifier: npq-senior-leadership ParticipantDeclarationCompletedRequest: description: An NPQ completed participant declaration type: object @@ -2309,19 +2323,19 @@ components: description: The type of course the participant is enrolled in type: string enum: - - npq-leading-teaching - - npq-leading-behaviour-culture - - npq-leading-teaching-development - - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-leading-primary-mathematics - npq-additional-support-offer - npq-early-headship-coaching-offer - - npq-leading-primary-mathematics - npq-senco - example: npq-headship + example: npq-senior-leadership has_passed: description: Whether the participant has failed or passed type: boolean @@ -2331,5 +2345,5 @@ components: participant_id: db3a7848-7308-4879-942a-c4a70ced400a declaration_type: completed declaration_date: '2021-05-31T02:21:32.000Z' - course_identifier: npq-leading-teaching + course_identifier: npq-senior-leadership has_passed: true diff --git a/public/api/docs/v3/swagger.yaml b/public/api/docs/v3/swagger.yaml index cd19c1afe3..1d42e081a4 100644 --- a/public/api/docs/v3/swagger.yaml +++ b/public/api/docs/v3/swagger.yaml @@ -403,6 +403,26 @@ paths: description: The participant declaration being voided content: application/json: + examples: + success: + value: + data: + id: d0b4a32e-a272-489e-b30a-cb17131457fc + type: participant-declaration + attributes: + participant_id: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: started + declaration_date: '2022-04-30' + course_identifier: npq-senior-leadership + state: voided + updated_at: '2021-05-31T02:22:32.000Z' + has_passed: + statement_id: cd3a12347-7308-4879-942a-c4a70ced400a + clawback_statement_id: cd3a12347-7308-4879-942a-c4a70ced400a + ineligible_for_funding_reason: duplicate_declaration + uplift_paid: true + lead_provider_name: Example Institute + created_at: '2021-05-31T02:22:32.000Z' schema: "$ref": "#/components/schemas/ParticipantDeclarationResponse" '401': @@ -2006,7 +2026,7 @@ components: has_passed: description: Whether the participant has failed or passed type: string - example: true + example: nullable: true statement_id: description: Unique ID of the statement the declaration will be paid @@ -2037,6 +2057,7 @@ components: lead_provider_name: description: The name of the provider that submitted the declaration type: string + example: Example Institute nullable: false created_at: description: The date the application was created @@ -2110,19 +2131,19 @@ components: type: string required: true enum: - - npq-leading-teaching - - npq-leading-behaviour-culture - - npq-leading-teaching-development - - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-leading-primary-mathematics - npq-additional-support-offer - npq-early-headship-coaching-offer - - npq-leading-primary-mathematics - npq-senco - example: npq-headship + example: npq-senior-leadership required: - participant_id - declaration_type @@ -2132,7 +2153,7 @@ components: participant_id: db3a7848-7308-4879-942a-c4a70ced400a declaration_type: started declaration_date: '2021-05-31T02:21:32.000Z' - course_identifier: npq-leading-teaching + course_identifier: npq-senior-leadership ParticipantDeclarationRetainedRequest: description: An NPQ participant retained declaration type: object @@ -2159,19 +2180,19 @@ components: description: The type of course the participant is enrolled in type: string enum: - - npq-leading-teaching - - npq-leading-behaviour-culture - - npq-leading-teaching-development - - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-leading-primary-mathematics - npq-additional-support-offer - npq-early-headship-coaching-offer - - npq-leading-primary-mathematics - npq-senco - example: npq-headship + example: npq-senior-leadership required: - participant_id - declaration_type @@ -2181,7 +2202,7 @@ components: participant_id: db3a7848-7308-4879-942a-c4a70ced400a declaration_type: retained-1 declaration_date: '2021-05-31T02:21:32.000Z' - course_identifier: npq-headship + course_identifier: npq-senior-leadership ParticipantDeclarationCompletedRequest: description: An NPQ completed participant declaration type: object @@ -2213,19 +2234,19 @@ components: description: The type of course the participant is enrolled in type: string enum: - - npq-leading-teaching - - npq-leading-behaviour-culture - - npq-leading-teaching-development - - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-leading-primary-mathematics - npq-additional-support-offer - npq-early-headship-coaching-offer - - npq-leading-primary-mathematics - npq-senco - example: npq-headship + example: npq-senior-leadership has_passed: description: Whether the participant has failed or passed type: boolean @@ -2235,5 +2256,5 @@ components: participant_id: db3a7848-7308-4879-942a-c4a70ced400a declaration_type: completed declaration_date: '2021-05-31T02:21:32.000Z' - course_identifier: npq-leading-teaching + course_identifier: npq-senior-leadership has_passed: true diff --git a/spec/requests/api/docs/v1/declarations_spec.rb b/spec/requests/api/docs/v1/declarations_spec.rb index bc31dfd132..b5dada10f8 100644 --- a/spec/requests/api/docs/v1/declarations_spec.rb +++ b/spec/requests/api/docs/v1/declarations_spec.rb @@ -22,6 +22,9 @@ 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}", @@ -34,7 +37,15 @@ "Participant declarations", "Void a declaration", "The participant declaration being voided", - "#/components/schemas/ParticipantDeclarationResponse" + "#/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 diff --git a/spec/requests/api/docs/v2/declarations_spec.rb b/spec/requests/api/docs/v2/declarations_spec.rb index e046364213..3b3143631d 100644 --- a/spec/requests/api/docs/v2/declarations_spec.rb +++ b/spec/requests/api/docs/v2/declarations_spec.rb @@ -22,6 +22,9 @@ 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}", @@ -34,7 +37,14 @@ "Participant declarations", "Void a declaration", "The participant declaration being voided", - "#/components/schemas/ParticipantDeclarationResponse" + "#/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 diff --git a/spec/requests/api/docs/v3/declarations_spec.rb b/spec/requests/api/docs/v3/declarations_spec.rb index a1a7f17515..99ff78b5fa 100644 --- a/spec/requests/api/docs/v3/declarations_spec.rb +++ b/spec/requests/api/docs/v3/declarations_spec.rb @@ -16,6 +16,9 @@ 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}", @@ -28,7 +31,14 @@ "Participant declarations", "Void a declaration", "The participant declaration being voided", - "#/components/schemas/ParticipantDeclarationResponse" + "#/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 diff --git a/spec/swagger_schemas/models/participant_declaration.rb b/spec/swagger_schemas/models/participant_declaration.rb index e60be9a896..bf63aeaa12 100644 --- a/spec/swagger_schemas/models/participant_declaration.rb +++ b/spec/swagger_schemas/models/participant_declaration.rb @@ -63,7 +63,7 @@ description: "[Deprecated - use state instead] Indicates whether this declaration has been voided", type: :boolean, nullable: true, - example: true, + example: false, }, state: { description: "Indicates the state of this payment declaration", @@ -83,7 +83,7 @@ description: "Whether the participant has failed or passed", type: :string, nullable: true, - example: true, + example: nil, }, }, }, @@ -125,12 +125,13 @@ h[:v3][:properties][:attributes][:properties][:has_passed] = { description: "Whether the participant has failed or passed", type: "string", # Need update when completed - example: true, + example: nil, nullable: true, } h[:v3][:properties][:attributes][:properties][:lead_provider_name] = { description: "The name of the provider that submitted the declaration", type: "string", + example: "Example Institute", nullable: false, } h[:v3][:properties][:attributes][:properties][:created_at] = { diff --git a/spec/swagger_schemas/requests/participant_declaration_completed_request.rb b/spec/swagger_schemas/requests/participant_declaration_completed_request.rb index 2e2686e643..232860f351 100644 --- a/spec/swagger_schemas/requests/participant_declaration_completed_request.rb +++ b/spec/swagger_schemas/requests/participant_declaration_completed_request.rb @@ -33,21 +33,8 @@ course_identifier: { description: "The type of course the participant is enrolled in", type: :string, - enum: %w[ - npq-leading-teaching - npq-leading-behaviour-culture - npq-leading-teaching-development - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership - npq-additional-support-offer - npq-early-headship-coaching-offer - npq-leading-primary-mathematics - npq-senco - ], - example: "npq-headship", + enum: Course::IDENTIFIERS, + example: Course::IDENTIFIERS.first, }, has_passed: { description: "Whether the participant has failed or passed", @@ -60,7 +47,7 @@ participant_id: "db3a7848-7308-4879-942a-c4a70ced400a", declaration_type: "completed", declaration_date: "2021-05-31T02:21:32.000Z", - course_identifier: "npq-leading-teaching", + course_identifier: Course::IDENTIFIERS.first, has_passed: true, }, }.freeze diff --git a/spec/swagger_schemas/requests/participant_declaration_retained_request.rb b/spec/swagger_schemas/requests/participant_declaration_retained_request.rb index 3d6c644128..fb5a4010b0 100644 --- a/spec/swagger_schemas/requests/participant_declaration_retained_request.rb +++ b/spec/swagger_schemas/requests/participant_declaration_retained_request.rb @@ -27,21 +27,8 @@ course_identifier: { description: "The type of course the participant is enrolled in", type: :string, - enum: %w[ - npq-leading-teaching - npq-leading-behaviour-culture - npq-leading-teaching-development - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership - npq-additional-support-offer - npq-early-headship-coaching-offer - npq-leading-primary-mathematics - npq-senco - ], - example: "npq-headship", + enum: Course::IDENTIFIERS, + example: Course::IDENTIFIERS.first, }, }, required: %i[ @@ -54,6 +41,6 @@ participant_id: "db3a7848-7308-4879-942a-c4a70ced400a", declaration_type: "retained-1", declaration_date: "2021-05-31T02:21:32.000Z", - course_identifier: "npq-headship", + course_identifier: Course::IDENTIFIERS.first, }, }.freeze diff --git a/spec/swagger_schemas/requests/participant_declaration_started_request.rb b/spec/swagger_schemas/requests/participant_declaration_started_request.rb index 8b64bb1ddc..28c949a2dd 100644 --- a/spec/swagger_schemas/requests/participant_declaration_started_request.rb +++ b/spec/swagger_schemas/requests/participant_declaration_started_request.rb @@ -30,21 +30,8 @@ description: "The type of course the participant is enrolled in", type: :string, required: true, - enum: %w[ - npq-leading-teaching - npq-leading-behaviour-culture - npq-leading-teaching-development - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership - npq-additional-support-offer - npq-early-headship-coaching-offer - npq-leading-primary-mathematics - npq-senco - ], - example: "npq-headship", + enum: Course::IDENTIFIERS, + example: Course::IDENTIFIERS.first, }, }, required: %i[ @@ -57,6 +44,6 @@ participant_id: "db3a7848-7308-4879-942a-c4a70ced400a", declaration_type: "started", declaration_date: "2021-05-31T02:21:32.000Z", - course_identifier: "npq-leading-teaching", + course_identifier: Course::IDENTIFIERS.first, }, }.freeze