You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
mv-api-spec/mv-openapi.yaml

432 lines
12 KiB

# Warning: this file has been automatically generated. All manual modifications will be lost, see README.md for details.
openapi: 3.0.0
info:
title: Mieux Voter
description: A poll application based on Majority Judgment (MJ).
version: 1.0.1-oas3
termsOfService: 'https://github.com/MieuxVoter'
contact:
name: Mieux Voter app developpers team
email: app@mieuxvoter.fr
servers:
- url: 'https://api.mieuxvoter.fr/v1'
description: Main (production) server
- url: 'https://sandboxapi.mieuxvoter.fr/v1'
description: Internal staging server for testing
paths:
/polls:
get:
operationId: get-polls
summary: Gets all polls.
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/poll'
post:
operationId: create-poll
summary: Creates a poll.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/poll'
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Id of the created poll.
links:
get-poll:
$ref: '#/components/links/get-poll'
update-poll:
$ref: '#/components/links/update-poll'
delete-poll:
$ref: '#/components/links/delete-poll'
create-judgment:
$ref: '#/components/links/create-judgment'
list-poll-results:
$ref: '#/components/links/list-poll-results'
'400':
description: Bad Request. Expect at least 2 candidates and a title.
'/polls/{poll-id}':
parameters:
- in: path
name: poll-id
required: true
schema:
type: integer
format: int64
get:
operationId: get-poll
summary: Gets a poll by ID
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/poll'
'404':
$ref: '#/components/responses/poll-not-found'
patch:
operationId: update-poll
summary: Updates a poll
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/poll'
security:
- {}
- pollAuth: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/poll'
delete:
operationId: delete-poll
summary: Deletes a poll
responses:
'200':
description: OK
'404':
$ref: '#/components/responses/poll-not-found'
security:
- pollAuth: []
'/polls/{poll-id}/judgments':
parameters:
- in: path
name: poll-id
required: true
schema:
type: string
post:
operationId: create-judgment
summary: Creates a judgment
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/judgment'
security:
- {}
- judgeAuth: []
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Id of the created judgment.
links:
get-judgment:
$ref: '#/components/links/get-judgment'
delete-judgment:
$ref: '#/components/links/delete-judgment'
'/polls/{poll-id}/judgments/{judgment-id}':
parameters:
- in: path
name: poll-id
required: true
schema:
type: string
- in: path
name: judgment-id
required: true
schema:
type: string
get:
operationId: get-judgment
summary: Gets a judgment by ID
responses:
'200':
description: A judgment object
content:
application/json:
schema:
$ref: '#/components/schemas/judgment'
delete:
operationId: delete-judgment
summary: Deletes a judgment
responses:
'200':
description: OK
'404':
$ref: '#/components/responses/judgment-not-found'
security:
- judgeAuth: []
'/polls/{poll-id}/judges':
parameters:
- in: path
name: poll-id
required: true
schema:
type: string
post:
operationId: add-judge-to-poll
description: Add a judge to a poll
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/judge'
responses:
'200':
description: Invitation was sent
content:
text/plain:
schema:
type: string
'404':
$ref: '#/components/responses/poll-not-found'
'/polls/{poll-id}/judges/{judge-id}/':
parameters:
- in: path
name: judge-id
required: true
schema:
type: string
get:
operationId: get-poll-judge
summary: Get a judge from a poll
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/judge'
'404':
$ref: '#/components/responses/judge-not-found'
security:
- {}
- pollAuth: []
delete:
operationId: delete-poll-judge
summary: Delete a judge from a poll
responses:
'200':
description: OK
'404':
$ref: '#/components/responses/judge-not-found'
security:
- pollAuth: []
'/polls/{poll-id}/results':
parameters:
- in: path
name: poll-id
required: true
schema:
type: string
get:
operationId: get-poll-results
description: Get results of a poll
responses:
'200':
description: OK
content:
text/plain:
schema:
$ref: '#/components/schemas/result'
'404':
$ref: '#/components/responses/poll-not-found'
components:
securitySchemes:
judgeAuth:
type: http
scheme: bearer
pollAuth:
type: http
scheme: bearer
resultAuth:
type: http
scheme: bearer
schemas:
judgment:
type: object
properties:
id:
type: string
readOnly: true
grade:
type: string
candidate:
type: object
properties:
id:
type: string
readOnly: true
name:
type: string
description: Unique but short name of the candidate.
judgments:
type: array
items:
$ref: '#/components/schemas/judgment'
description: The judgments received by this candidate.
grade:
type: object
properties:
id:
type: string
readOnly: true
name:
type: string
description: 'Unique but short name of the grade, like "Excellent" or "To reject".'
judge:
type: object
properties:
id:
type: string
readOnly: true
has-voted:
type: string
poll-id:
type: string
mail:
type: object
description: >-
Send a mail at the creation of the judge. The mail is not kept in
memory.
poll:
type: object
properties:
id:
type: string
readOnly: true
title:
type: string
description: 'As <title>, I find these candidates:'
candidates:
type: array
minItems: 2
maxItems: 20
items:
$ref: '#/components/schemas/candidate'
description: The candidates being judged in a poll.
grades:
type: array
items:
$ref: '#/components/schemas/grade'
description: The grades on which one judges a candidate.
judges:
type: array
items:
$ref: '#/components/schemas/judge'
description: The judges that are allowed to participate to the election.
restrict_judges:
type: boolean
description: Can anyone create a judge?
error:
type: object
properties:
code:
type: string
message:
type: string
required:
- code
- message
result:
type: object
properties:
poll:
$ref: '#/components/schemas/poll'
ranking:
type: array
items:
type: integer
format: int16
links:
get-poll:
operationId: get-poll
parameters:
pollId: $response.body#/id
description: >
The `id` value returned in the response can be used as the `poll-id`
parameter in GET /polls/{poll-id}.
update-poll:
operationId: update-poll
parameters:
pollId: $response.body#/id
description: >
The `id` value returned in the response can be used as the `poll-id`
parameter in PATCH /polls/{poll-id}.
delete-poll:
operationId: delete-poll
parameters:
pollId: $response.body#/id
description: >
The `id` value returned in the response can be used as the `poll-id`
parameter in DELETE /polls/{poll-id}.
create-judgment:
operationId: create-judgment
parameters:
userId: $response.body#/id
description: >
The `id` value returned in the response can be used as the `poll-id`
parameter in POST /polls/{poll-id}/judgments.
list-poll-results:
operationId: list-poll-results
parameters:
pollId: $response.body#/id
description: >
The `id` value returned in the response can be used as the `poll-id`
parameter in GET /polls/{poll-id}/results.
get-judgment:
operationId: get-judgment
parameters:
judgmentId: $response.body#/id
description: >
The `id` value returned in the response can be used as the `judgment-id`
parameter in GET /polls/{poll-id}/judgments/{judgment-id}.
delete-judgment:
operationId: delete-judgment
parameters:
judgmentId: $response.body#/id
description: >
The `id` value returned in the response can be used as the `judgment-id`
parameter in DELETE /polls/{poll-id}/judgments/{judgment-id}.
responses:
poll-not-found:
description: The specified poll was not found
content:
application/json:
schema:
$ref: '#/components/schemas/error'
judgment-not-found:
description: The specified judgment was not found
content:
application/json:
schema:
$ref: '#/components/schemas/error'
judge-not-found:
description: The specified judge was not found
content:
application/json:
schema:
$ref: '#/components/schemas/error'