From 8d5c34e6ed732b3386f206d0d1224611aeb8f3ed Mon Sep 17 00:00:00 2001 From: Pablo M Date: Fri, 5 Jul 2024 15:52:19 +0200 Subject: [PATCH] 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