Update Teacher Training API to return selectable_school

app/serializers/api/public/v1/serializable_provider.rb

@@ -23,7 +23,8 @@ class SerializableProvider < JSONAPI::Serializable::Resource
                    :telephone,
                    :email,
                    :can_sponsor_skilled_worker_visa,
-                   :can_sponsor_student_visa
+                   :can_sponsor_student_visa,
+                   :selectable_school
 
         attribute :accredited_body do
           @object.accredited_provider?

bin/build-docs

@@ -0,0 +1,7 @@
+#!/bin/env bash
+
+docker build --target middleman -t publish-docs .
+mkdir -p public/docs
+container_id=$(docker create publish-docs)
+docker cp $container_id:/public/. public/docs
+docker rm $container_id

docs/source/release-notes.html.md.erb

@@ -6,6 +6,10 @@ weight: 2
 # Release Notes
 
 
+## 20 August 2024
+
+- Add `selectable_school` property to `ProviderAttributes`. Providers with this value as true allow Candidates to choose specific school placements in the User Interface.
+
 ## 19 July 2023
 
 - Add `discard` filter to `ProviderFilter`. This boolean field returns only decomissioned providers. `discarded_at` is returned in the `ProviderAttributes`.

guides/api.md

@@ -7,15 +7,33 @@ Our API is documented using [OpenAPI](https://swagger.io/specification/). You ca
 We use [Tech Docs](https://github.com/alphagov/tech-docs-gem) to build documentation. To update documentation, run the command below which will generate an open api specification file. The docker build will then take these files to generate the static site.
 
 
+### Develop and test API documentation
+
+
+1. If we want to change the documentation, go to `swagger/public_vx` and make changes to the yml files.
+
+2. Run the swaggerize command to generate a new api_spec.json
+
 Use the following command to generate OpenAPI specification:
 
 ```sh
 bundle exec rake rswag:specs:swaggerize
 ```
 
+3. We build the documentation in a separate container to the main app and copy the contents into the main image.
 
-To develop and preview the tech docs you can start and run with [Middleman](https://github.com/middleman/middleman)
 
-```sh
-cd docs && bundle install && bundle exec middleman
+```shell
+bin/build-docs
 ```
+
+This will:
+
+1. build a container only of the docs
+2. copy the built docs to `public/docs`
+3. allow you to visit `http://publish.localhost:3001/docs/` and see your changes
+
+#### Confirm the openapi specs
+
+    http://publish.localhost:3001/api-docs/public_v1/api_spec.json
+

spec/controllers/api/public/v1/providers_controller_spec.rb

@@ -338,7 +338,8 @@
                 telephone
                 email
                 can_sponsor_skilled_worker_visa
-                can_sponsor_student_visa]
+                can_sponsor_student_visa
+                selectable_school]
           end
 
           before do
@@ -540,7 +541,8 @@
             'telephone' => provider.telephone,
             'email' => provider.email,
             'can_sponsor_student_visa' => provider.can_sponsor_student_visa,
-            'can_sponsor_skilled_worker_visa' => provider.can_sponsor_skilled_worker_visa
+            'can_sponsor_skilled_worker_visa' => provider.can_sponsor_skilled_worker_visa,
+            'selectable_school' => provider.selectable_school
           }
         }
       end

spec/factories/providers.rb

@@ -35,6 +35,7 @@
     can_sponsor_student_visa { [true, false].sample }
     can_sponsor_skilled_worker_visa { [true, false].sample }
     synonyms { Faker::Lorem.words(number: 0..3) }
+    selectable_school { true }
 
     trait :with_name do
       provider_name { 'Test Name' }

spec/serializers/api/public/v1/serializable_provider_spec.rb

@@ -15,6 +15,7 @@
   it { is_expected.to have_type 'providers' }
 
   it { is_expected.to have_attribute(:postcode).with_value(provider.postcode) }
+  it { is_expected.to have_attribute(:selectable_school).with_value(provider.selectable_school) }
   it { is_expected.to have_attribute(:provider_type).with_value(provider.provider_type) }
   it { is_expected.to have_attribute(:region_code).with_value(provider.region_code) }
   it { is_expected.to have_attribute(:train_with_disability).with_value(provider.train_with_disability) }

swagger/public_v1/api_spec.json

@@ -7,7 +7,7 @@
       "name": "DfE",
       "email": "[email protected]"
     },
-    "description": "API for DfE's postgraduate teacher training course service."
+    "description": "API for DfE's teacher training course service."
   },
   "servers": [
     {
@@ -335,14 +335,14 @@
             "nullable": true,
             "format": "markdown",
             "description": "This field is being deprecated after 2024 recruitment cycle.",
-            "example": ""
+            "example": null
           },
           "personal_qualities": {
             "type": "string",
             "nullable": true,
             "format": "markdown",
             "description": "This field is being deprecated after 2024 recruitment cycle.",
-            "example": ""
+            "example": null
           },
           "program_type": {
             "type": "string",
@@ -1272,6 +1272,12 @@
             "example": "2023-07-18T15:23:15Z",
             "format": "date-time",
             "nullable": true
+          },
+          "selectable_school": {
+            "type": "boolean",
+            "description": "Can candidates choose their placement school",
+            "example": true,
+            "nullable": false
           }
         }
       },
@@ -2243,7 +2249,7 @@
           },
           {
             "description": "Get the second page of courses for a provider",
-            "command": "curl -X GET https://api.publish-teacher-training-courses.service.gov.uk/api/public/v1/recruitment_cycles/2020/provideers/B20/courses?page[page]=2"
+            "command": "curl -X GET https://api.publish-teacher-training-courses.service.gov.uk/api/public/v1/recruitment_cycles/2020/providers/B20/courses?page[page]=2"
           }
         ],
         "responses": {
@@ -2272,7 +2278,7 @@
             "name": "year",
             "in": "path",
             "required": true,
-            "description": "The starting year of the recruitment cycle.Also accepts \"current\" for the current recruitment cycle. Defaults to current recruitment cycle if invalid year (eg \"1066\") is provided",
+            "description": "The starting year of the recruitment cycle. Also accepts \"current\" for the current recruitment cycle. Defaults to current recruitment cycle if invalid year (eg \"1066\") is provided",
             "example": 2024,
             "schema": {
               "type": "string"

swagger/public_v1/component_schemas/CourseAttributes.yml

@@ -207,21 +207,15 @@ properties:
     nullable: true
     format: markdown
     description: >-
-      Any non-academic qualifications or documents the applicant may need.
-    example: >-
-      You'll need to provide confirmation you have the health and
-      physical capacity to commence training, and a Disclosure and
-      Barring Service (DBS) certificate.
+      This field is being deprecated after 2024 recruitment cycle.
+    example:
   personal_qualities:
     type: string
     nullable: true
     format: markdown
     description: >-
-      Any skills, motivation and experience the provider is looking for in applicants.
-    example: >-
-      We are looking for applicants who have the potential to become
-      outstanding teachers, and who are able to work independently on
-      their studies while training in a school context.
+      This field is being deprecated after 2024 recruitment cycle.
+    example:
   program_type:
     type: string
     description: >-

swagger/public_v1/component_schemas/ProviderAttributes.yml

@@ -150,3 +150,8 @@ properties:
     example: "2023-07-18T15:23:15Z"
     format: date-time
     nullable: true
+  selectable_school:
+    type: boolean
+    description: "Can candidates choose their placement school"
+    example: true
+    nullable: false