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

651 lines
18 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.
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-ballot:
$ref: '#/components/links/create-ballot'
list-poll-results:
$ref: '#/components/links/list-poll-results'
'400':
description: Bad Request. Expect at least 2 proposals 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}/ballots':
parameters:
- in: path
name: poll-id
required: true
schema:
type: string
post:
operationId: create-ballot
summary: Creates a ballot
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ballot'
security:
- {}
- participantAuth: []
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Id of the created ballot.
links:
get-ballot:
$ref: '#/components/links/get-ballot'
delete-ballot:
$ref: '#/components/links/delete-ballot'
'/polls/{poll-id}/ballots/{ballot-id}':
parameters:
- in: path
name: poll-id
required: true
schema:
type: string
- in: path
name: ballot-id
required: true
schema:
type: string
get:
operationId: get-ballot
summary: Gets a ballot by ID
responses:
'200':
description: A ballot object
content:
application/json:
schema:
$ref: '#/components/schemas/ballot'
delete:
operationId: delete-ballot
summary: Deletes a ballot
responses:
'200':
description: OK
'404':
$ref: '#/components/responses/ballot-not-found'
security:
- participantAuth: []
'/polls/{poll-id}/participants':
parameters:
- in: path
name: poll-id
required: true
schema:
type: string
post:
operationId: add-participant-to-poll
description: Add a participant to a poll
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/participant'
responses:
'200':
description: Invitation was sent
content:
text/plain:
schema:
type: string
'404':
$ref: '#/components/responses/poll-not-found'
'/polls/{poll-id}/participants/{participant-id}/':
parameters:
- in: path
name: participant-id
required: true
schema:
type: string
get:
operationId: get-poll-participant
summary: Get a participant from a poll
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/participant'
'404':
$ref: '#/components/responses/participant-not-found'
security:
- {}
- pollAuth: []
delete:
operationId: delete-poll-participant
summary: Delete a participant from a poll
responses:
'200':
description: OK
'404':
$ref: '#/components/responses/participant-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'
/users:
get:
operationId: get-users
summary: Gets all users.
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/user'
post:
operationId: create-user
summary: Creates an user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/user'
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Id of the created user.
links:
get-user:
$ref: '#/components/links/get-user'
update-user:
$ref: '#/components/links/update-user'
delete-user:
$ref: '#/components/links/delete-user'
'/users/{user-id}':
parameters:
- in: path
name: user-id
required: true
schema:
type: integer
format: int64
get:
operationId: get-user
summary: Gets a user by ID
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/user'
'404':
$ref: '#/components/responses/user-not-found'
patch:
operationId: update-user
summary: Updates a user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/user'
security:
- {}
- userAuth: []
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/user'
delete:
operationId: delete-user
summary: Deletes a user
responses:
'200':
description: OK
'404':
$ref: '#/components/responses/user-not-found'
security:
- userAuth: []
components:
securitySchemes:
participantAuth:
type: http
scheme: bearer
pollAuth:
type: http
scheme: bearer
resultAuth:
type: http
scheme: bearer
userAuth:
type: http
scheme: bearer
schemas:
ballot:
type: object
properties:
id:
type: integer
description: A unique identifier
example: 4
readOnly: true
mention:
type: integer
description: >-
The mention item, according to the mentions array defined when
creating the poll.
example: 2
proposal:
type: object
properties:
id:
type: integer
description: A unique identifier.
readOnly: true
example: 4
name:
type: string
description: Unique but short name of the proposal.
example: A new school
ballots:
type: array
description: The ballots received by this proposal.
items:
$ref: '#/components/schemas/ballot'
description:
type: string
description: An optional description of the proposal
example: This school would welcome 500 pupils.
required:
- name
mention:
type: object
properties:
id:
type: integer
description: A unique identifier
example: 0
readOnly: true
name:
type: string
description: >-
Unique but short name of the mention, like *Excellent* or *To
reject*.
example: Excellent
description:
type: string
description: An optional description of the mention
example: 'In this poll, the mention *To reject* disqualifies the proposal.'
required:
- name
participant:
type: object
properties:
id:
type: string
description: A unique identifier.
example: JtRm05yjMAuFCI2uwnFp
readOnly: true
description:
type: string
description: An optional description of the participant.
example: John Doe
has-participed:
type: boolean
description: >-
True if the participant already participed to the poll, False
otherwise.
example: true
poll-id:
type: string
description: The identifier of the poll that the participant participates on.
example: 1jDe1e5eF_IkaYPuoIYX
user-id:
type: string
description: The identifier of the user.
example: 1jDe1e5eF_IkaYPuoIYX
mail:
type: string
description: >-
The mail that will eventually created at the creation of the
participant (not kept in memory).
example: john-doe@example.com
required:
- poll-id
poll:
type: object
properties:
id:
type: string
description: A unique identifier
example: 1jDe1e5eF_IkaYPuoIYX
readOnly: true
title:
type: string
example: What project should our neighbourhood invest in for the next year?
description: The title of the poll
description:
type: string
description: A description of the poll
example: null
proposals:
type: array
description: The proposals being voted in a poll.
minItems: 2
maxItems: 20
items:
$ref: '#/components/schemas/proposal'
mentions:
type: array
description: The mentions on which one participant vote to a proposal.
minItems: 2
maxItems: 10
items:
$ref: '#/components/schemas/mention'
participants:
type: array
description: The participants that are allowed to participate to the election.
items:
$ref: '#/components/schemas/participant'
user-id:
type: string
description: 'Organizer id. If not given, a dummy user is created.'
restrict-participants:
type: boolean
description: 'True if anyone can participate to this poll, False otherwise.'
example: false
required:
- title
- proposals
error:
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 participant was not found
required:
- code
- message
result:
type: object
properties:
poll:
$ref: '#/components/schemas/poll'
ranking:
type: array
description: >-
An array representing mentions level for each proposal, according to
the mentions list, following the order of the proposals array
defined when the related poll has been created.
example:
- 0
- 6
- 3
- 2
- 2
minItems: 2
maxItems: 20
items:
type: integer
format: int16
required:
- ranking
- poll
user:
type: object
properties:
id:
type: integer
description: A unique identifier
example: 0
readOnly: true
name:
type: string
description: Unique user-name
example: john.doe
description:
type: string
description: An optional description of the user
example: >-
John Doe is a multiple-use name that is used when the true name of a
person is unknown or is being intentionally concealed
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-ballot:
operationId: create-ballot
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}/ballots.
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-ballot:
operationId: get-ballot
parameters:
ballotId: $response.body#/id
description: >
The `id` value returned in the response can be used as the `ballot-id`
parameter in GET /polls/{poll-id}/ballots/{ballot-id}.
delete-ballot:
operationId: delete-ballot
parameters:
ballotId: $response.body#/id
description: >
The `id` value returned in the response can be used as the `ballot-id`
parameter in DELETE /polls/{poll-id}/ballots/{ballot-id}.
get-user:
operationId: get-user
parameters:
userId: $response.body#/id
description: >
The `id` value returned in the response can be used as the `user-id`
parameter in GET /users/{user-id}.
update-user:
operationId: update-user
parameters:
userId: $response.body#/id
description: >
The `id` value returned in the response can be used as the `user-id`
parameter in PATCH /users/{user-id}.
delete-user:
operationId: delete-user
parameters:
userId: $response.body#/id
description: >
The `id` value returned in the response can be used as the `user-id`
parameter in DELETE /users/{user-id}.
responses:
poll-not-found:
description: The specified poll was not found
content:
application/json:
schema:
$ref: '#/components/schemas/error'
ballot-not-found:
description: The specified ballot was not found
content:
application/json:
schema:
$ref: '#/components/schemas/error'
participant-not-found:
description: The specified participant was not found
content:
application/json:
schema:
$ref: '#/components/schemas/error'
user-not-found:
description: The specified user was not found
content:
application/json:
schema:
$ref: '#/components/schemas/error'