Add work schedule description + use 404 where appropriate

docs/api/apiv3/components/schemas/non_working_day_collection_model.yml

@@ -14,7 +14,7 @@ allOf:
         properties:
           self:
             allOf:
-              - $ref: "./link.yml"
+              - $ref: './link.yml'
               - description: |-
                   This non working days collection
 

docs/api/apiv3/components/schemas/non_working_day_model.yml

@@ -13,10 +13,12 @@ properties:
   date:
     type: string
     format: date
-    description: Date of the non-working day.
+    description: |-
+      Date of the non-working day.
   name:
     type: string
-    description: Descriptive name for the non-working day.
+    description: |-
+      Descriptive name for the non-working day.
   _links:
     type: object
     required:

docs/api/apiv3/components/schemas/week_day_collection_model.yml

@@ -14,7 +14,7 @@ allOf:
         properties:
           self:
             allOf:
-              - $ref: "./link.yml"
+              - $ref: './link.yml'
               - description: |-
                   This week days collection
 

docs/api/apiv3/components/schemas/week_day_model.yml

@@ -36,5 +36,5 @@ example:
   working: false
   _links:
     self:
-      href: "/api/v3/day/week/5"
+      href: /api/v3/day/week/5
       title: Friday

docs/api/apiv3/components/schemas/week_day_self_link_model.yml

@@ -6,7 +6,7 @@ description: |-
 properties:
   self:
     allOf:
-      - "$ref": "./link.yml"
+      - $ref: './link.yml'
       - description: |-
           This week day resource link.
 

docs/api/apiv3/openapi-spec.yml

@@ -846,5 +846,6 @@ tags:
   - "$ref": "./tags/views.yml"
   - "$ref": "./tags/wiki_pages.yml"
   - "$ref": "./tags/work_packages.yml"
+  - "$ref": "./tags/work_schedule.yml"
 security:
   - BasicAuth: []

docs/api/apiv3/paths/days_non_working.yml

@@ -5,7 +5,6 @@ post:
   operationId: create_non_working_day
   tags:
     - Work Schedule
-    - Non working days
   description: |-
     Marks a day as being a non-working day.
 
@@ -21,13 +20,15 @@ post:
           name: 'Christmas'
   responses:
     '200':
-      description: OK
+      description: |-
+        OK
       content:
         application/hal+json:
           schema:
             $ref: '../components/schemas/non_working_day_model.yml'
     '400':
-      description: Returned if the client sends invalid request parameters.
+      description: |-
+        Returned if the client sends invalid request parameters.
       content:
         application/hal+json:
           schema:
@@ -37,7 +38,8 @@ post:
             errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
             message: The request body was not a single JSON object.
     '403':
-      description: Returned if the client does not have sufficient permissions.
+      description: |-
+        Returned if the client does not have sufficient permissions.
       content:
         application/hal+json:
           schema:

docs/api/apiv3/paths/days_non_working_date.yml

@@ -5,7 +5,6 @@ get:
   operationId: view_non_working_day
   tags:
     - Work Schedule
-    - Non working days
   description: |-
     Returns the non-working day information for a given date.
   parameters:
@@ -20,19 +19,22 @@ get:
       example: '2022-05-06'
   responses:
     '200':
-      description: OK
+      description: |-
+        OK
       content:
         application/hal+json:
           schema:
             $ref: '../components/schemas/non_working_day_model.yml'
     '400':
-      description: Returned if the client sends invalid request parameters.
+      description: |-
+        Returned if the client sends invalid request parameters.
       content:
         application/hal+json:
           schema:
             $ref: '../components/schemas/error_response.yml'
     '404':
-      description: Returned if the given date is not a non-working day.
+      description: |-
+        Returned if the given date is not a non-working day.
       content:
         application/hal+json:
           schema:
@@ -47,7 +49,6 @@ patch:
   operationId: update_non_working_day
   tags:
     - Work Schedule
-    - Non working days
   description: |-
     Update the non-working day information for a given date.
   parameters:
@@ -72,19 +73,22 @@ patch:
 
   responses:
     '200':
-      description: OK
+      description: |-
+        OK
       content:
         application/hal+json:
           schema:
             $ref: '../components/schemas/non_working_day_model.yml'
     '400':
-      description: Returned if the client sends invalid request parameters.
+      description: |-
+        Returned if the client sends invalid request parameters.
       content:
         application/hal+json:
           schema:
             $ref: '../components/schemas/error_response.yml'
     '404':
-      description: Returned if the given date is not a non-working day.
+      description: |-
+        Returned if the given date is not a non-working day.
       content:
         application/hal+json:
           schema:
@@ -94,19 +98,13 @@ patch:
             errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
             message: The requested resource could not be found.
 
-# TODO: add missing description, missing tags, missing parameters, and missing response codes
 delete:
-  summary: Removes a day from the non-working days
+  summary: Removes a non-working day
   operationId: delete_non_working_day
   tags:
     - Work Schedule
-    - Non working days
   description: |-
-    Removes the day of the given day from the non-working days known.
-
-    Trying to remove a date which is not a non-working day, by calling the same
-    endpoint twice for example, will succeed in both cases and return a 204
-    status.
+    Removes the non-working day at the given date.
   parameters:
     - name: date
       in: path
@@ -134,3 +132,14 @@ delete:
             _type: Error
             errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
             message: The date is not valid.
+    '404':
+      description: |-
+        Returned if the given date is not a non-working day.
+      content:
+        application/hal+json:
+          schema:
+            $ref: '../components/schemas/error_response.yml'
+          example:
+            _type: Error
+            errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
+            message: The requested resource could not be found.

docs/api/apiv3/paths/days_week.yml

@@ -5,19 +5,19 @@ get:
   operationId: list_week_days
   tags:
     - Work Schedule
-    - Non working days
-    - Week days
   description: |-
     Lists week days with work schedule information.
   responses:
     '200':
-      description: OK
+      description: |-
+        OK
       content:
         application/hal+json:
           schema:
             $ref: '../components/schemas/week_day_collection_model.yml'
     '400':
-      description: Returned if the client sends invalid request parameters
+      description: |-
+        Returned if the client sends invalid request parameters
       content:
         application/hal+json:
           schema:
@@ -32,50 +32,25 @@ patch:
   operationId: update_week_days
   tags:
     - Work Schedule
-    - Non working days
-    - Week days
   description: |-
-    Update all week days with work schedule information.
+    Update multiple week days with work schedule information.
   requestBody:
     content:
       application/json:
         schema:
           $ref: ../components/schemas/week_day_collection_write_model.yml
-        example:
-          _type: Collection
-          _embedded:
-            elements:
-              - _type: WeekDay
-                day: 1
-                working: true
-              - _type: WeekDay
-                day: 2
-                working: true
-              - _type: WeekDay
-                day: 3
-                working: true
-              - _type: WeekDay
-                day: 4
-                working: true
-              - _type: WeekDay
-                day: 5
-                working: true
-              - _type: WeekDay
-                day: 6
-                working: false
-              - _type: WeekDay
-                day: 7
-                working: false
 
   responses:
     '200':
-      description: OK
+      description: |-
+        OK
       content:
         application/hal+json:
           schema:
             $ref: '../components/schemas/week_day_collection_model.yml'
     '400':
-      description: Returned if the client sends invalid request parameters
+      description: |-
+        Returned if the client sends invalid request parameters
       content:
         application/hal+json:
           schema:
@@ -84,17 +59,14 @@ patch:
             _type: Error
             errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
             message: The request body was not a single JSON object.
-    '422':
+    '404':
       description: |-
-        Occurs if the request body was correctly formatted, but some properties lead to errors in the validation
-        process. This happens for example if not every days were sent.
+        Returned if a week day resource can not be found.
       content:
         application/hal+json:
           schema:
-            $ref: "../components/schemas/error_response.yml"
-          examples:
-            response:
-              value:
-                _type: Error
-                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
-                message: The request was invalid. Must send all days of the week.
+            $ref: '../components/schemas/error_response.yml'
+          example:
+            _type: Error
+            errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
+            message: The requested resource could not be found.

docs/api/apiv3/paths/days_week_day.yml

@@ -5,7 +5,6 @@ get:
   operationId: view_week_day
   tags:
     - Work Schedule
-    - Week day
   description: |-
     View a week day and its attributes.
   parameters:
@@ -20,7 +19,8 @@ get:
         maximum: 7
   responses:
     '200':
-      description: OK
+      description: |-
+        OK
       content:
         application/hal+json:
           schema:
@@ -36,20 +36,17 @@ get:
             _type: Error
             errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
             message: The request body was not a single JSON object.
-    '422':
+    '404':
       description: |-
-        Occurs if the request body was correctly formatted, but some properties lead to errors in the validation
-        process. This happens for example if the day is out of the 1-7 range.
+        Returned if the day is out of the 1-7 range.
       content:
         application/hal+json:
           schema:
-            $ref: "../components/schemas/error_response.yml"
-          examples:
-            response:
-              value:
-                _type: Error
-                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
-                message: The request was invalid. Expected day to be between 1 and 7.
+            $ref: '../components/schemas/error_response.yml'
+          example:
+            _type: Error
+            errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
+            message: The requested resource could not be found.
 
 patch:
   summary: Update a week day attributes
@@ -61,7 +58,6 @@ patch:
     work packages scheduling once the behavior has been specified.
   tags:
     - Work Schedule
-    - Week day
   parameters:
     - name: day
       in: path

docs/api/apiv3/paths/days_work_schedule.yml

@@ -5,7 +5,6 @@ get:
   operationId: list_non_working_days
   tags:
     - Work Schedule
-    - Non working days
   description: |-
     Lists non-working days for a given date interval.
 
@@ -39,13 +38,15 @@ get:
         type: string
   responses:
     '200':
-      description: OK
+      description: |-
+        OK
       content:
         application/hal+json:
           schema:
             $ref: '../components/schemas/non_working_day_collection_model.yml'
     '400':
-      description: Returned if the client sends invalid request parameters.
+      description: |-
+        Returned if the client sends invalid request parameters.
       content:
         application/hal+json:
           schema:

docs/api/apiv3/tags/work_schedule.yml

@@ -0,0 +1,15 @@
+---
+name: Work Schedule
+description: |-
+  The work schedule defines if days are working days or non-working days.
+
+  A day can be a non-working day if any of these two conditions are met:
+
+    - the day is a recurring non-working week day: a weekend day. For instance
+      Sunday is not worked in most countries;
+    - the day has been defined as a non-working day: national bank holidays or
+      other days deemed special. For instance the 1st of January is New Year's
+      day and is a bank holiday in most countries.
+
+  Endpoints can define which week days are working/non-working days, and which
+  dates are non-working days.