From 06adcb5f111928aa34795bbd917bc4dd9495e699 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nathana=C3=ABl=20Jourdane?= Date: Mon, 25 May 2020 17:46:02 +0200 Subject: [PATCH] Improve schemas descriptions and add examples --- openapi/components/schemas/candidate.yaml | 4 +++- openapi/components/schemas/error.yaml | 4 ++++ openapi/components/schemas/grade.yaml | 4 +++- openapi/components/schemas/judge.yaml | 11 +++++++++-- openapi/components/schemas/judgment.yaml | 2 ++ openapi/components/schemas/poll.yaml | 14 +++++++++----- openapi/components/schemas/result.yaml | 6 ++++++ 7 files changed, 36 insertions(+), 9 deletions(-) diff --git a/openapi/components/schemas/candidate.yaml b/openapi/components/schemas/candidate.yaml index f5a52a6..7fbba1f 100644 --- a/openapi/components/schemas/candidate.yaml +++ b/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. diff --git a/openapi/components/schemas/error.yaml b/openapi/components/schemas/error.yaml index fecef03..6bb55a1 100644 --- a/openapi/components/schemas/error.yaml +++ b/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 diff --git a/openapi/components/schemas/grade.yaml b/openapi/components/schemas/grade.yaml index bd23855..f1b0194 100644 --- a/openapi/components/schemas/grade.yaml +++ b/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 diff --git a/openapi/components/schemas/judge.yaml b/openapi/components/schemas/judge.yaml index 5114595..04dfd20 100644 --- a/openapi/components/schemas/judge.yaml +++ b/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 diff --git a/openapi/components/schemas/judgment.yaml b/openapi/components/schemas/judgment.yaml index e0cd858..3e8716a 100644 --- a/openapi/components/schemas/judgment.yaml +++ b/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. diff --git a/openapi/components/schemas/poll.yaml b/openapi/components/schemas/poll.yaml index e231886..e1519fc 100644 --- a/openapi/components/schemas/poll.yaml +++ b/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 , 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 diff --git a/openapi/components/schemas/result.yaml b/openapi/components/schemas/result.yaml index f196349..8e684d4 100644 --- a/openapi/components/schemas/result.yaml +++ b/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