Update swagger docs with declaration endpoints #1504
Conversation
padv2010
force-pushed
the
CPDLP-3103-ts-7-update-swagger-docs-with-declaration-endpoints
branch
from
0c458ac
to
f923fad
Compare
padv2010
changed the title
| 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) |
There was a problem hiding this comment.
You can omit these if you aren't writing a custom response example, it will default to the ParticipantDeclarationResponse passed in on line 61
There was a problem hiding this comment.
Addressed in 4e0af42
| @@ -8,13 +8,6 @@ | |||
| produces "application/json" | |||
| security [api_key: []] | |||
|
|
|||
There was a problem hiding this comment.
I think this file should be deleted? it looks like it was replaced/renamed with create on existing resource?
There was a problem hiding this comment.
I split it in two, because one post is for a resource that already exist, and the other one is for a new one. I tried to merge both and the code looked complicated.
| }, | ||
| attributes: { | ||
| anyOf: [ | ||
| { "$ref": "#/components/schemas/ParticipantDeclarationStartedRequest" }, |
There was a problem hiding this comment.
I wonder if there's any way to get this pulling through into the swagger-ui, it seems to only show one request example 🤔
There was a problem hiding this comment.
@ethax-ross I have not been able to find how to do it, sorry
| type: :string, | ||
| example: "2021,2022", | ||
| }, | ||
| delivery_partner_id: { |
There was a problem hiding this comment.
There are no delivery partners in NPQ; I think this should be training_status?
There was a problem hiding this comment.
Addressed in 34a5363. I have not been able to find a reference to training_status
There was a problem hiding this comment.
👍 I think I was looking at the ECFParticipantFilter by accident, looks good now.
| description: "An NPQ completed participant declaration", | ||
| type: :object, | ||
| required: %i[ | ||
| participant_id |
There was a problem hiding this comment.
It's a bit of a faff, but to get the swagger-ui to generate properly and mark as required you need to add required: true to the indivudual properties below as well, so:
participant_id: {
description: "The unique id of the participant",
type: :string,
format: :uuid,
example: "db3a7848-7308-4879-942a-c4a70ced400a",
required: true
},
We need to do this in all request schemas
There was a problem hiding this comment.
There was a problem hiding this comment.
So the issue with not putting it also on the type and attributes and individual attributes like participant_id is that it doesn't mark it as required 'in all the ways'... I'm not sure if we can that much about this, but here's how it looks if you do it everywhere:
| Before | After |
|---|---|
 |
 |
Here's the diff:
diff --git a/spec/swagger_schemas/requests/participant_declaration_request.rb b/spec/swagger_schemas/requests/participant_declaration_request.rb
index 76cb809a..ed6529de 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 956f601d..8b64bb1d 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 @@ PARTICIPANT_DECLARATION_STARTED_REQUEST = {
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 @@ PARTICIPANT_DECLARATION_STARTED_REQUEST = {
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
| type: :string, | ||
| nullable: false, | ||
| example: "started", | ||
| enum: %w[ |
There was a problem hiding this comment.
Could populate from the model (we don't have extended declarations), so:
enum: Schedule::DECLARATION_TYPES
The example can also be populated: example: Schedule::DECLARATION_TYPES.first
There was a problem hiding this comment.
Addressed in f5275af
| type: :string, | ||
| nullable: false, | ||
| example: "npq-leading-teaching", | ||
| enum: %w[ |
There was a problem hiding this comment.
Ditto pull from Course::IDENTIFIERS and the example can use Course::IDENTIFIERS.first
There was a problem hiding this comment.
Addressed in f5275af
| type: :string, | ||
| nullable: false, | ||
| example: "submitted", | ||
| enum: %w[ |
There was a problem hiding this comment.
Addressed in f5275af
| example: "2021-05-31T02:22:32.000Z", | ||
| }, | ||
| has_passed: { | ||
| description: "The date the declaration was last updated", |
There was a problem hiding this comment.
Whether the participant has failed or passed
There was a problem hiding this comment.
Addressed in f5275af
| }, | ||
| }, | ||
| }, | ||
| v2: { |
There was a problem hiding this comment.
Instead of copy/pasting here we could deep_dup the hash and tap it to modify only the changed parts (see other schemas for an example). v2 drops the voided/eligible_for_payment fields and v3 builds on v2 and adds statement_id, clawback_statement_id, uplift_paid, lead_provider_name, ineligible_for_funding_reason and created_at
There was a problem hiding this comment.
Addressed in f5275af
leandroalemao
force-pushed
the
CPDLP-3094
branch
2 times, most recently
from
5aa4ff6
to
c871d86
Compare
padv2010
force-pushed
the
CPDLP-3103-ts-7-update-swagger-docs-with-declaration-endpoints
branch
3 times, most recently
from
9b01e9e
to
f5275af
Compare
|
Review app deployed to https://npq-registration-review-1504-web.test.teacherservices.cloud/ |
padv2010
force-pushed
the
CPDLP-3103-ts-7-update-swagger-docs-with-declaration-endpoints
branch
from
8d5c34e
to
82e7d2c
Compare
Context
Ticket: https://dfedigital.atlassian.net/browse/CPDNPQ-000
Description
Add API docs for all the declaration endpoints in NPQ in v1/v2/v3 for the GET/POST participant-declarations in all versions including any errors as in About the API - Manage training for early career teachers . Add the PUT void declarations in all versions.