Merge pull request #124 from tomcdonnell/hotfix-master/SA-15353

Update docs to match actual response [SA-15353] master

Author: armatronic

openapi/components/schemas/dateTime.yaml

@@ -5,37 +5,5 @@ description: |
   * a RFC3339 string
   * an object, which contains a datetime in several formats
 oneOf:
-  - type: string
-    format: date-time
-  - type: object
-    readOnly: true
-    deprecated: true
-    description: |
-      This read-only object representation is deprecated and will be
-      removed eventually: it exists only for compatibility with existing
-      API endpoints.
-
-      If using this object representation, please use the "json" property
-      and perform localization using client-side libraries.
-    required:
-      - json
-    properties:
-      database:
-        type: string
-        description: |
-          A database representation of the date.
-      unixTimestamp:
-        type: integer
-        format: int64
-        description: |
-          The date as a Unix timestamp.
-      local:
-        type: string
-        description: |
-          A string representation of the date, localized to the Schoolbox
-          instance's settings.
-      json:
-        type: string
-        format: date-time
-        description: |
-          The date as a RFC3339 string.
+  - $ref: dateTimeString.yaml
+  - $ref: dateTimeObject.yaml

openapi/components/schemas/dateTimeObject.yaml

@@ -0,0 +1,44 @@
+title: Datetime Object
+type: object
+readOnly: true
+#
+# This has been commented out so that the description from the parent will be displayed in the generated docs.
+# The description in the parent should describe the purpose of the particular date field, whereas this description
+# describes the particulars of this representation.
+#
+#description: |
+#  A JSON representation of a datetime.
+#  * an object, which contains a datetime in several formats
+#
+#  This read-only object representation is deprecated and will be
+#  removed eventually: it exists only for compatibility with existing
+#  API endpoints.
+#
+#  If using this object representation, please use the "json" property
+#  and perform localization using client-side libraries.
+required:
+  - json
+properties:
+  database:
+    type: string
+    description: |
+      A database representation of the date.  Eg. "2018-01-28 00:00:00"
+    example: "2018-01-28 00:00:00"
+  unixTimestamp:
+    type: integer
+    format: int64
+    description: |
+      The date as a Unix timestamp.  Eg. 1517058000
+    example: 1517058000
+  local:
+    type: string
+    description: |
+      A string representation of the date, localized to the Schoolbox
+      instance's settings.  Eg. "28/01/2018 12:00am".
+    example: "28/01/2018 12:00am"
+  json:
+    type: string
+    format: date-time
+    description: |
+      The date as a RFC3339 string. Eg. "2018-01-28T00:00:00+11:00".
+    example: "2018-01-28T00:00:00+11:00"

openapi/components/schemas/dateTimeString.yaml

@@ -0,0 +1,5 @@
+title: Datetime
+type: string
+description: The date as a RFC3339 string. eg. "2018-01-28T00:00:00+11:00".
+format: date-time
+example: "2018-01-28T00:00:00+11:00"

openapi/components/schemas/news/author.yaml

@@ -23,3 +23,8 @@ properties:
     description: |
       The author's full name: usually, this is the title, first name and last
       name joined together.
+  preferredName:
+    type: string
+    nullable: true
+  givenName:
+    type: string

openapi/components/schemas/news/commonFields.yaml

@@ -46,10 +46,25 @@ properties:
     allOf:
       - description: |
           When was the article published?
-      - $ref: ../dateTime.yaml
+          
+          This read-only object representation is deprecated.  It will be
+          replaced in 23.1 with an RFC3339 string eg. "2018-01-28T00:00:00+11:00".
+      - $ref: ../dateTimeObject.yaml
   topics:
     type: array
     description: |
       A list of topics which are applicable to the article.
     items:
-      $ref: ../news/topic.yaml
+      type: object
+      properties:
+        name:
+          type: string
+          description: |
+            A human-readable name for the topic.
+        slug:
+          type: string
+          description: |
+            A machine-readable name for the topic.
+
+
+

openapi/components/schemas/news/statusDate.yaml

@@ -2,4 +2,7 @@ allOf:
   - description: |
       When did the article's status change to its current
       value?
-  - $ref: ../dateTime.yaml
+      
+      This read-only object representation is deprecated.  It will be
+      replaced in 23.1 with an RFC3339 string eg. "2018-01-28T00:00:00+11:00".
+  - $ref: ../dateTimeObject.yaml

openapi/components/schemas/news/topic.yaml

@@ -15,4 +15,4 @@ properties:
   sequence:
     type: integer
     description: |
-      The order in which this topic will display in a topic list.
+      The order in which this topic will display in a topic list.