MTDSA-21816: Add correct headers to OAS documentation (#150)

Author: EdCope

resources/public/api/conf/1.0/amend.yaml

@@ -40,6 +40,12 @@ responses:
     headers:
       X-CorrelationId:
         $ref: './common/headers.yaml#/components/parameters/correlationId'
+      Deprecation:
+        $ref: "./common/headers.yaml#/components/parameters/deprecationHeader"
+      Sunset:
+        $ref: "./common/headers.yaml#/components/parameters/sunsetHeader"
+      Link:
+        $ref: "./common/headers.yaml#/components/parameters/linkHeader"
     content:
       application/json:
         schema:
@@ -49,12 +55,17 @@ responses:
             value:
               $ref: './examples/disclosures/amend_response.json'
 
-
   "400":
     description: Bad request
     headers:
       X-CorrelationId:
         $ref: './common/headers.yaml#/components/parameters/correlationId'
+      Deprecation:
+        $ref: "./common/headers.yaml#/components/parameters/deprecationHeader"
+      Sunset:
+        $ref: "./common/headers.yaml#/components/parameters/sunsetHeader"
+      Link:
+        $ref: "./common/headers.yaml#/components/parameters/linkHeader"
     content:
       application/json:
         schema:
@@ -84,18 +95,31 @@ responses:
     headers:
       X-CorrelationId:
         $ref: './common/headers.yaml#/components/parameters/correlationId'
+      Deprecation:
+        $ref: "./common/headers.yaml#/components/parameters/deprecationHeader"
+      Sunset:
+        $ref: "./common/headers.yaml#/components/parameters/sunsetHeader"
+      Link:
+        $ref: "./common/headers.yaml#/components/parameters/linkHeader"
     content:
       application/json:
         schema:
           $ref: './schemas/error-response.yaml'
         examples:
           CLIENT_OR_AGENT_NOT_AUTHORISED:
             $ref: './common/errors.yaml#/components/examples/clientOrAgentNotAuthorised'
+
   "404":
     description: Not Found
     headers:
       X-CorrelationId:
         $ref: './common/headers.yaml#/components/parameters/correlationId'
+      Deprecation:
+        $ref: "./common/headers.yaml#/components/parameters/deprecationHeader"
+      Sunset:
+        $ref: "./common/headers.yaml#/components/parameters/sunsetHeader"
+      Link:
+        $ref: "./common/headers.yaml#/components/parameters/linkHeader"
     content:
       application/json:
         schema:

resources/public/api/conf/1.0/common/headers.yaml

@@ -62,3 +62,33 @@ components:
         type: string
         example: "-"
       required: false
+
+    linkHeader:
+      name: "Link"
+      in: header
+      description: |
+        URL of the documentation for the API.
+      schema:
+        type: string
+        example: "https://developer.service.hmrc.gov.uk/api-documentation/docs/api/service/individuals-disclosures-api"
+      required: false
+
+    deprecationHeader:
+      name: "Deprecation"
+      in: header
+      description: |
+        The deprecation date/time for this endpoint.
+      schema:
+        type: string
+        example: "Sun, 01 Jan 2023 23:59:59 GMT"
+      required: false
+
+    sunsetHeader:
+      name: "Sunset"
+      in: header
+      description: |
+        The earliest date/time this endpoint will become unavailable after deprecation.
+      schema:
+        type: string
+        example: "Sun, 02 Jul 2023 23:59:59 GMT"
+      required: false

resources/public/api/conf/1.0/delete.yaml

@@ -28,12 +28,24 @@ responses:
     headers:
       X-CorrelationId:
         $ref: './common/headers.yaml#/components/parameters/correlationId'
+      Deprecation:
+        $ref: "./common/headers.yaml#/components/parameters/deprecationHeader"
+      Sunset:
+        $ref: "./common/headers.yaml#/components/parameters/sunsetHeader"
+      Link:
+        $ref: "./common/headers.yaml#/components/parameters/linkHeader"
 
   "400":
     description: Bad request
     headers:
       X-CorrelationId:
         $ref: './common/headers.yaml#/components/parameters/correlationId'
+      Deprecation:
+        $ref: "./common/headers.yaml#/components/parameters/deprecationHeader"
+      Sunset:
+        $ref: "./common/headers.yaml#/components/parameters/sunsetHeader"
+      Link:
+        $ref: "./common/headers.yaml#/components/parameters/linkHeader"
     content:
       application/json:
         schema:
@@ -55,6 +67,12 @@ responses:
     headers:
       X-CorrelationId:
         $ref: './common/headers.yaml#/components/parameters/correlationId'
+      Deprecation:
+        $ref: "./common/headers.yaml#/components/parameters/deprecationHeader"
+      Sunset:
+        $ref: "./common/headers.yaml#/components/parameters/sunsetHeader"
+      Link:
+        $ref: "./common/headers.yaml#/components/parameters/linkHeader"
     content:
       application/json:
         schema:
@@ -67,6 +85,12 @@ responses:
     headers:
       X-CorrelationId:
         $ref: './common/headers.yaml#/components/parameters/correlationId'
+      Deprecation:
+        $ref: "./common/headers.yaml#/components/parameters/deprecationHeader"
+      Sunset:
+        $ref: "./common/headers.yaml#/components/parameters/sunsetHeader"
+      Link:
+        $ref: "./common/headers.yaml#/components/parameters/linkHeader"
     content:
       application/json:
         schema: