Improve schemas descriptions and add examples

openapi/components/schemas/candidate.yaml

@@ -2,12 +2,14 @@ type: object
 properties:
   id:
     type: string
+    description: A unique identifier.
     readOnly: true
   name:
     type: string
     description: Unique but short name of the candidate.
+    example: A new school
   judgments:
     type: array
+    description: The judgments received by this candidate.
     items:
       $ref: ./judgment.yaml
-    description: The judgments received by this candidate.

openapi/components/schemas/error.yaml

@@ -2,8 +2,12 @@ type: object
 properties:
   code:
     type: string
+    description: The HTTP code of the response
+    example: 404
   message:
     type: string
+    description: The response details
+    example: The specified judge was not found
 required:
   - code
   - message

openapi/components/schemas/grade.yaml

@@ -2,7 +2,9 @@ type: object
 properties:
   id:
     type: string
+    description: A unique identifier
     readOnly: true
   name:
     type: string
-    description: 'Unique but short name of the grade, like "Excellent" or "To reject".'
+    description: Unique but short name of the grade, like "Excellent" or "To reject".
+    example: Excellent

openapi/components/schemas/judge.yaml

@@ -2,11 +2,18 @@ type: object
 properties:
   id:
     type: string
+    description: A unique identifier
+    example: JtRm05yjMAuFCI2uwnFp
     readOnly: true
   has-voted:
-    type: string
+    type: boolean
+    description: True if the judge already voted on the poll, False otherwise
+    example: true
   poll-id:
     type: string
+    description: The identifier of the poll that the judge participates on.
+    example: '1jDe1e5eF_IkaYPuoIYX'
   mail:
     type: object
-    description: Send a mail at the creation of the judge. The mail is not kept in memory.
+    description: The mail that will eventually created at the creation of the judge (not kept in memory).
+    example: john-doe@example.com

openapi/components/schemas/judgment.yaml

@@ -2,6 +2,8 @@ type: object
 properties:
   id:
     type: string
+    description: A unique identifier
     readOnly: true
   grade:
     type: string
+    description: The grade item, according to the grades array defined when creating the poll.

openapi/components/schemas/poll.yaml

@@ -2,27 +2,31 @@ type: object
 properties:
   id:
     type: string
+    description: 'A unique identifier'
+    example: '1jDe1e5eF_IkaYPuoIYX'
     readOnly: true
   title:
     type: string
-    description: 'As <title>, I find these candidates:'
+    example: 'What project should our neighbourhood invest in for the next year?'
+    description: 'The title of the poll'
   candidates:
     type: array
+    description: The candidates being judged in a poll.
     minItems: 2
     maxItems: 20
     items:
       $ref: ./candidate.yaml
-    description: The candidates being judged in a poll.
   grades:
     type: array
+    description: The grades on which one judges a candidate.
     items:
       $ref: ./grade.yaml
-    description: The grades on which one judges a candidate.
   judges:
     type: array
+    description: The judges that are allowed to participate to the election.
     items:
       $ref: ./judge.yaml
-    description: The judges that are allowed to participate to the election.
   restrict_judges:
     type: boolean
-    description: Can anyone create a judge?
+    description: True if anyone can participate to this poll, False otherwise.
+    example: false

openapi/components/schemas/result.yaml

@@ -1,9 +1,15 @@
 type: object
 properties:
   poll:
+    type: object
+    description: The poll belonging to this result.
     $ref: ./poll.yaml
   ranking:
     type: array
+    description: An array representing grades level for each candidate,
+      according to the grades list, following the order of the candidates array
+      defined when the related poll has been created.
+    examples: [0, 6, 3, 2, 2]
     items:
       type: integer
       format: int16