Browse Source

Improve schemas descriptions and add examples

pull/13/head
Nathanaël Jourdane 3 years ago
committed by guhur
parent
commit
06adcb5f11
  1. 4
      openapi/components/schemas/candidate.yaml
  2. 4
      openapi/components/schemas/error.yaml
  3. 4
      openapi/components/schemas/grade.yaml
  4. 11
      openapi/components/schemas/judge.yaml
  5. 2
      openapi/components/schemas/judgment.yaml
  6. 14
      openapi/components/schemas/poll.yaml
  7. 6
      openapi/components/schemas/result.yaml

4
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.

4
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

4
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

11
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

2
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.

14
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

6
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
Loading…
Cancel
Save