Merge pull request #483 from NHSDigital/release/2025-01-29

Release/2025 01 29

Author: jameslinnell

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 2025-01-29
+- [PI-714] Update Swagger for readibility
+- [PI-759] Integration test timeout
+
 ## 2025-01-24
 - [PI-744] Create a Product Team (ProductID)
 - Dependabot: pydantic

VERSION

@@ -1 +1 @@
-2025.01.24
+2025.01.29

changelog/2025-01-29.md

@@ -0,0 +1,2 @@
+- [PI-714] Update Swagger for readibility
+- [PI-759] Integration test timeout

infrastructure/swagger/05_paths.yaml

@@ -11,11 +11,29 @@ x-definitions:
       passthroughBehavior: when_no_match
       contentHandling: CONVERT_TO_TEXT
 
+tags:
+  - name: Core Product ID Endpoints
+    description: Create, Read and Delete Product IDs
+  - name: Core EPR Creation Endpoints
+    description: Core EPR API creation endpoints
+  - name: Core EPR Read Endpoints
+    description: Core EPR API read endpoints
+  - name: Core EPR Deletion Endpoints
+    description: Core EPR API deletion endpoints
+  - name: EPR
+    description: EPR API endpoints
+  - name: SDS
+    description: Search Results provided for the SDS FHIR API
+
 paths:
   /_status:
     get:
-      summary: Retrieve the current Status (GET)
+      summary: Retrieve the current Status of the API (GET)
+      description: >
+        Get the current status of the API
       operationId: status
+      tags:
+        - Status
       responses:
         "200":
           $ref: "#/components/responses/StatusOK"
@@ -36,6 +54,10 @@ paths:
     post:
       operationId: createproductteam
       summary: Create a Product Team resource (POST)
+      description: >
+        Create a Product Team. This is needed in order to create a Product.
+      tags:
+        - Core Product ID Endpoints
       requestBody:
         $ref: "#/components/requestBodies/ProductTeamCreateRequestBody"
       responses:
@@ -60,6 +82,10 @@ paths:
     get:
       operationId: readproductteam
       summary: Read a Product Team resource (GET)
+      description: |
+        - Retrieve a Product Team using a product team ID.
+      tags:
+        - Core Product ID Endpoints
       parameters:
         - $ref: "#/components/parameters/ProductTeamId"
         - $ref: "#/components/parameters/HeaderVersion"
@@ -81,6 +107,8 @@ paths:
     post:
       operationId: createproductteamepr
       summary: Create a Product Team (Epr) resource (POST)
+      tags:
+        - Core EPR Creation Endpoints
       requestBody:
         $ref: "#/components/requestBodies/ProductTeamCreateRequestBody"
       responses:
@@ -105,6 +133,8 @@ paths:
     get:
       operationId: readproductteamepr
       summary: Read a Product Team (Epr) resource (GET)
+      tags:
+        - Core EPR Read Endpoints
       parameters:
         - $ref: "#/components/parameters/ProductTeamId"
         - $ref: "#/components/parameters/HeaderVersion"
@@ -126,6 +156,8 @@ paths:
     post:
       operationId: createproductendpoint
       summary: Create a Product resource (POST)
+      tags:
+        - Core EPR Creation Endpoints
       description: |
         This endpoint creates a new Product resource for the specified Product Team.
         **Requirements:**
@@ -153,6 +185,10 @@ paths:
     get:
       operationId: searchCpmProduct
       summary: Retrieve all Products associated with a Product Team (GET)
+      description: |
+        - Retrieve all products for a Product Team using a product team ID.
+      tags:
+        - Core EPR Read Endpoints
       parameters:
         - $ref: "#/components/parameters/ProductTeamId"
         - $ref: "#/components/parameters/HeaderVersion"
@@ -174,6 +210,10 @@ paths:
     get:
       operationId: readproductendpoint
       summary: Read a Product resource (GET)
+      description: |
+        - Retrieve a product using a product team ID and product ID.
+      tags:
+        - Core EPR Read Endpoints
       parameters:
         - $ref: "#/components/parameters/ProductTeamId"
         - $ref: "#/components/parameters/ProductId"
@@ -194,6 +234,10 @@ paths:
     delete:
       operationId: deleteproductendpoint
       summary: Delete a Product resource (DELETE)
+      description: |
+        - Delete a product using a product team ID and product ID.
+      tags:
+        - Core EPR Deletion Endpoints
       parameters:
         - $ref: "#/components/parameters/ProductTeamId"
         - $ref: "#/components/parameters/ProductId"
@@ -216,6 +260,8 @@ paths:
     post:
       operationId: createproductforeprendpoint
       summary: Create an EPR Product resource (POST)
+      tags:
+        - EPR
       description: |
         This endpoint creates a new EPR Product resource for the specified Product Team.
         **Requirements:**
@@ -245,6 +291,10 @@ paths:
   : get:
       operationId: searchDeviceReferenceData
       summary: Retrieve all Data Reference Data resources associated with a Product (GET)
+      description: |
+        - Retrieve all Device Reference Data objects using a product team ID and product ID.
+      tags:
+        - Core EPR Read Endpoints
       parameters:
         - $ref: "#/components/parameters/ProductTeamId"
         - $ref: "#/components/parameters/ProductId"
@@ -266,7 +316,10 @@ paths:
     post:
       operationId: createDeviceReferenceData
       summary: Create a Device Reference Data resource (POST)
-      description: This endpoint has not yet been configured. Do not use.
+      tags:
+        - Core EPR Creation Endpoints
+      description: |
+        **This endpoint has not yet been configured. Do not use.**
       parameters:
         - $ref: "#/components/parameters/ProductTeamId"
         - $ref: "#/components/parameters/ProductId"
@@ -294,12 +347,16 @@ paths:
   : post:
       operationId: createDeviceReferenceDataMessageSet
       summary: Create a Device Reference Data Message Set resource (POST)
+      tags:
+        - Core EPR Creation Endpoints
       description: |
         This endpoint creates a Device Reference Data Message Set resource for the specified Product.
         **Requirements:**
         - A valid Product Team must exist
         - A valid EPR Product must already exist under the Product Team
         - There can be no existing MHS MessageSet DRD for the EPR Product already
+        - Questionnaire response required: **spine_mhs_message_sets**
+        - Refer to the questionnaire endpoint for details on this questionnaire response. **/questionnaire/spine_mhs_message_sets**
       parameters:
         - $ref: "#/components/parameters/ProductTeamId"
         - $ref: "#/components/parameters/ProductId"
@@ -327,12 +384,16 @@ paths:
   : post:
       operationId: createDeviceReferenceDataAdditionalInteractions
       summary: Create a Device Reference Data Additional Interactions resource (POST)
+      tags:
+        - Core EPR Creation Endpoints
       description: |
         This endpoint creates a Device Reference Data Additional Interactions resource for the specified Product.
         **Requirements:**
         - A valid Product Team must exist
         - A valid EPR Product must already exist under the Product Team
         - There can be no existing AS AdditionalInteractions DRD for the EPR Product already
+        - Questionnaire response required: **spine_as_additional_interactions**
+        - Refer to the questionnaire endpoint for details on this questionnaire response. **/questionnaire/spine_as_additional_interactions**
       parameters:
         - $ref: "#/components/parameters/ProductTeamId"
         - $ref: "#/components/parameters/ProductId"
@@ -360,6 +421,10 @@ paths:
   : get:
       operationId: readDeviceReferenceData
       summary: Read a Device Reference Data resource (GET)
+      description: >
+        Retrieve a Device Reference Data entity using a product team ID, product ID and Device Reference Data ID.
+      tags:
+        - Core EPR Read Endpoints
       parameters:
         - $ref: "#/components/parameters/ProductTeamId"
         - $ref: "#/components/parameters/ProductId"
@@ -384,8 +449,10 @@ paths:
     post:
       operationId: createDevice
       summary: Create a Device resource (POST)
+      tags:
+        - Core EPR Creation Endpoints
       description: |
-        This endpoint has not yet been configured. Do not use.
+        **This endpoint has not yet been configured. Do not use.**
       parameters:
         - $ref: "#/components/parameters/ProductTeamId"
         - $ref: "#/components/parameters/ProductId"
@@ -413,6 +480,10 @@ paths:
   : get:
       operationId: readDevice
       summary: Read a Device resource (GET)
+      description: >
+        Retrieve a device using a product team ID, product ID and device ID.
+      tags:
+        - Core EPR Read Endpoints
       parameters:
         - $ref: "#/components/parameters/ProductTeamId"
         - $ref: "#/components/parameters/ProductId"
@@ -437,14 +508,17 @@ paths:
   : post:
       operationId: createDeviceMessageHandlingSystem
       summary: Create a Message Handling System Device resource (POST)
+      tags:
+        - Core EPR Creation Endpoints
       description: |
         This endpoint creates a new Message Handling System Device resource for the specified Product.
         **Requirements:**
         - A valid Product Team must exist
         - A valid Product must exist under the Product Team
         - One existing MHS Message Set Device Reference Data must be present for the Product
         - No existing MHS device for the product
-        - Must provide a spine_mhs questionnaire response
+        - Questionnaire response required: **spine_mhs**
+        - Refer to the questionnaire endpoint for details on this questionnaire response. **/questionnaire/spine_mhs**
       parameters:
         - $ref: "#/components/parameters/ProductTeamId"
         - $ref: "#/components/parameters/ProductId"
@@ -472,14 +546,17 @@ paths:
   : post:
       operationId: createDeviceAccreditedSystem
       summary: Create a Accredited System Device resource (POST)
+      tags:
+        - Core EPR Creation Endpoints
       description: |
         This endpoint creates a new Accredited System Device resource for the specified Product.
         **Requirements:**
         - A valid Product Team must exist
         - A valid Product must exist under the Product Team
         - One existing MHS Message Set Device Reference Data must be present for the Product
         - One existing AS Additional Interactions Device Reference Data must be present for the Product
-        - Must provide a spine_as questionnaire response
+        - Questionnaire response required: **spine_as**
+        - Refer to the questionnaire endpoint for details on this questionnaire response. **/questionnaire/spine_as**
       parameters:
         - $ref: "#/components/parameters/ProductTeamId"
         - $ref: "#/components/parameters/ProductId"
@@ -507,6 +584,10 @@ paths:
     get:
       operationId: searchsdsdevice
       summary: Retrieve Device resources for SDS FHIR API (GET)
+      description: >
+        Retrieve a list of Devices to be used primarily by the SDS FHIR API.
+      tags:
+        - SDS
       parameters:
         - $ref: "#/components/parameters/NhsIdCode"
         - $ref: "#/components/parameters/NhsMhsManOrg"
@@ -530,6 +611,10 @@ paths:
     get:
       operationId: searchsdsendpoint
       summary: Retrieve Endpoint resources for SDS FHIR API (GET)
+      description: >
+        Retrieve a list of Endpoints to be used primarily by the SDS FHIR API.
+      tags:
+        - SDS
       parameters:
         - $ref: "#/components/parameters/NhsIdCode"
         - $ref: "#/components/parameters/NhsMhsInteration"
@@ -553,6 +638,16 @@ paths:
     get:
       operationId: readQuestionnaire
       summary: Read a Questionnaire resource (GET)
+      description: |
+        Retrieve information about the format of a questionnaire to be answered. To be used in conjunction with creating Devices and DeviceReferenceData. System generated fields are not required and will be populated by CPM. **Please note: Although examples are given it's impossible to layout exactly what format a questionnaire will take as the questionnaire itself uses json_schema to allow custom formats.**
+
+        IDs available are
+        - spine_mhs
+        - spine_as
+        - spine_mhs_message_sets
+        - spine_as_additional_interactions
+      tags:
+        - Core EPR Read Endpoints
       parameters:
         - $ref: "#/components/parameters/QuestionnaireId"
         - $ref: "#/components/parameters/HeaderVersion"

infrastructure/swagger/07_components--schemas--domain.yaml

@@ -147,8 +147,41 @@ components:
     Questionnaire:
       type: object
       properties:
-        tbc:
+        name:
+          type: string
+        version:
           type: string
+        json_schema:
+          type: object
+          properties:
+            $schema:
+              type: string
+            type:
+              type: string
+            properties:
+              type: object
+              properties:
+                question:
+                  type: object
+                  properties:
+                    type:
+                      type: string
+                    system generated:
+                      type: boolean
+      example:
+        name: "questionnaire_1"
+        version: "1"
+        json_schema:
+          $schema: "http://json-schema.org/draft-07/schema#"
+          type: "object"
+          properties:
+            question_1:
+              type: "string"
+              system generated: false
+            question_2:
+              type: "string"
+              system generated: true
+          required: question_1
 
     ProductSearchResponse:
       type: object
@@ -229,16 +262,25 @@ components:
           type: string
         name:
           type: string
+        status:
+          type: string
         product_id:
           type: string
         product_team_id:
           type: string
         ods_code:
           type: string
-        status:
-          type: string
         environment:
           type: string
+        keys:
+          type: array
+          items:
+            type: object
+            properties:
+              key_type:
+                type: string
+              key_value:
+                type: string
         created_on:
           type: string
         updated_on:

infrastructure/swagger/08_components--schemas--other.yaml

@@ -4,6 +4,7 @@ components:
     HeaderVersion:
       type: string
       pattern: "^[1-9][0-9]?(\\.[0-9])?$"
+      example: 1
 
     HeaderRequestId:
       type: string