From 847bbb4a2c5663d21836713adc846c9d26e46d63 Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 05:16:37 +0200 Subject: [PATCH 01/40] docs: Review the README --- README.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3661704..d1eb30c 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,20 @@ # Mieux Voter OpenAPI Definition -TODO: -CI on Jenkins +This reposority hosts the OpenAPI specification for the API of MieuxVoter, +a Majority Judgment polling application spearheaded by the french nonprofit +[MieuxVoter.fr](https://mieuxvoter.fr). + + +## TODO + +- [x] Draft a spec +- [ ] CI on Jenkins +- [ ] Link to generated doc/sandbox +- [ ] Localization (how?) +- [ ] … + + +----- ## Working on your OpenAPI Definition @@ -22,6 +35,7 @@ Bundles the definition to the dist folder. #### `npm test` Validates the definition. + ## Contribution Guide Below is a sample contribution guide. The tools From 97e4752457c90aa4197acfa6692257940c5b4da0 Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 05:17:00 +0200 Subject: [PATCH 02/40] docs: review the NPM package configuration Perhaps irrelevant since this may never be published publicly as a package, but it's good practice nonetheless and may help with SEO. --- package.json | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index 93439db..680007b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,15 @@ { - "name": "mieux-voter", + "name": "mieux-voter-openapi", "version": "1.0.0", + "description": "OpenAPI specifications for a Majority Judgment polling application made by MieuxVoter.fr", + "keywords": ["majority", "judgment", "poll", "polling", "api", "rest", "openapi", "democracy", "vote", "libre", "open"], + "homepage": "https://github.com/MieuxVoter/mv-api-spec", + "bugs": "https://github.com/MieuxVoter/mv-api-spec/issues", + "repository": { + "type": "git", + "url": "https://github.com/MieuxVoter/mv-api-spec.git" + }, + "license": "MIT", "dependencies": { "@redocly/openapi-cli": "^0.12.10" }, From f0690c7b1ea690c4afa6eec754958bd83837a5b0 Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 05:17:26 +0200 Subject: [PATCH 03/40] feat: add a UUID to the proposals Mostly to see if it works. If it does, we should probably add UUIDs everywhere. --- openapi/components/schemas/proposal.yaml | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/openapi/components/schemas/proposal.yaml b/openapi/components/schemas/proposal.yaml index 143e144..0c6888e 100644 --- a/openapi/components/schemas/proposal.yaml +++ b/openapi/components/schemas/proposal.yaml @@ -1,22 +1,30 @@ +# Thing unto which the participants pass judgments. +# Also known as Candidate. type: object properties: id: type: integer - description: A unique identifier. + description: A unique identifier for the proposal, in the poll. readOnly: true example: 4 + uuid: + type: uuid + description: A Universally Unique IDentifier for the proposal. (version 4) + readOnly: true + example: bb788552-727d-470b-827e-d7796248d293 name: type: string description: Unique but short name of the proposal. example: A new school + description: + type: string + description: An optional description of the proposal. (no markup allowed) + example: This school would welcome 500 pupils. ballots: type: array description: The ballots received by this proposal. items: $ref: ./ballot.yaml - description: - type: string - description: An optional description of the proposal - example: This school would welcome 500 pupils. + required: - name From 5d58bc6bf26b6674917b79be775e2daf0a2be01b Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 05:30:02 +0200 Subject: [PATCH 04/40] refactor: grade --> grade (1/2) Rationale: `grade` comes from a frencophone bias. --- openapi/components/schemas/ballot.yaml | 7 +++++-- openapi/components/schemas/mention.yaml | 13 ++++++++----- openapi/components/schemas/poll.yaml | 12 ++++++------ openapi/components/schemas/result.yaml | 4 ++-- 4 files changed, 21 insertions(+), 15 deletions(-) diff --git a/openapi/components/schemas/ballot.yaml b/openapi/components/schemas/ballot.yaml index efb0644..a17de99 100644 --- a/openapi/components/schemas/ballot.yaml +++ b/openapi/components/schemas/ballot.yaml @@ -5,7 +5,10 @@ properties: description: A unique identifier example: 4 readOnly: true - mention: + grade: type: integer - description: The mention item, according to the mentions array defined when creating the poll. + description: > + One grade of the grading defined when creating the poll. + Zero (0) means the worst grade, and it goes upwards from there, + up to the size of the grading, minus one. example: 2 diff --git a/openapi/components/schemas/mention.yaml b/openapi/components/schemas/mention.yaml index dc84d6c..fe39a24 100644 --- a/openapi/components/schemas/mention.yaml +++ b/openapi/components/schemas/mention.yaml @@ -2,16 +2,19 @@ type: object properties: id: type: integer - description: A unique identifier + description: > + Unique identifier of the grade in its grading. + Zero (0) is the worst grade, and it goes upwards. example: 0 readOnly: true name: type: string - description: Unique but short name of the mention, like *Excellent* or *To reject*. - example: Excellent + description: > + Unique but short name of the grade, like "Excellent" or "To reject". + example: Good description: type: string - description: An optional description of the mention - example: In this poll, the mention *To reject* disqualifies the proposal. + description: An optional description of the grade. + example: In this poll, the grade "To reject" disqualifies the proposal. required: - name diff --git a/openapi/components/schemas/poll.yaml b/openapi/components/schemas/poll.yaml index 3f20575..0684620 100644 --- a/openapi/components/schemas/poll.yaml +++ b/openapi/components/schemas/poll.yaml @@ -2,7 +2,7 @@ type: object properties: id: type: string - description: A unique identifier + description: A unique identifier. example: 1jDe1e5eF_IkaYPuoIYX readOnly: true title: @@ -12,7 +12,7 @@ properties: description: type: string description: A description of the poll - example: + example: proposals: type: array description: The proposals being voted in a poll. @@ -20,13 +20,13 @@ properties: maxItems: 20 items: $ref: ./proposal.yaml - mentions: + grades: type: array - description: The mentions on which one participant vote to a proposal. + description: The grades on which one participant vote to a proposal. minItems: 2 maxItems: 10 items: - $ref: ./mention.yaml + $ref: ./grade.yaml participants: type: array description: The participants that are allowed to participate to the election. @@ -37,7 +37,7 @@ properties: 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. + description: True if anyone can participate in this poll, False otherwise. example: false required: - title diff --git a/openapi/components/schemas/result.yaml b/openapi/components/schemas/result.yaml index 8f9f873..c2b6bd3 100644 --- a/openapi/components/schemas/result.yaml +++ b/openapi/components/schemas/result.yaml @@ -4,8 +4,8 @@ properties: $ref: ./poll.yaml ranking: type: array - description: An array representing mentions level for each proposal, - according to the mentions list, following the order of the proposals array + description: An array representing grades level for each proposal, + according to the grades list, following the order of the proposals array defined when the related poll has been created. example: [0, 6, 3, 2, 2] minItems: 2 From bf4b0b2f12f0e1ce9b72fc051f432df9cec700e3 Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 05:31:05 +0200 Subject: [PATCH 05/40] refactor: mention --> grade (2/2) --- openapi/components/schemas/{mention.yaml => grade.yaml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename openapi/components/schemas/{mention.yaml => grade.yaml} (100%) diff --git a/openapi/components/schemas/mention.yaml b/openapi/components/schemas/grade.yaml similarity index 100% rename from openapi/components/schemas/mention.yaml rename to openapi/components/schemas/grade.yaml From 441b558eabec33f632b4c30d4f51fce2df3bc167 Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 05:46:23 +0200 Subject: [PATCH 06/40] chore: freshen up the LICENSE Copyright --- LICENSE | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE b/LICENSE index d41b8bd..54f0e21 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2016 Ivan Goncharov +Copyright (c) 2020 MieuxVoter.fr Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal From 28d2bd00a8f70adf4fcd1b398823911e9fea5b16 Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 05:47:01 +0200 Subject: [PATCH 07/40] chore: review the components README --- openapi/components/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openapi/components/README.md b/openapi/components/README.md index 26eaeb5..b8e8513 100644 --- a/openapi/components/README.md +++ b/openapi/components/README.md @@ -1,5 +1,5 @@ Reusable components -=========== +=================== * You can create the following folders here: - `schemas` - reusable [Schema Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaObject) @@ -11,4 +11,4 @@ Reusable components - `links` - reusable [Link Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#linkObject) - `callbacks` - reusable [Callback Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#callbackObject) - `securitySchemes` - reusable [Security Scheme Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#securitySchemeObject) -* Filename of files inside the folders represent component name, e.g. `Customer.yaml` +* Filename of files inside the folders represent component name, e.g. `customer.yaml` From 61e0c03d94ff25ee6e64ea4f5d60a377e47dff74 Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 05:51:22 +0200 Subject: [PATCH 08/40] chore: capitalize things (it just looks prettier) --- openapi/mv-openapi-root.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/mv-openapi-root.yaml b/openapi/mv-openapi-root.yaml index 0216316..95e5a20 100644 --- a/openapi/mv-openapi-root.yaml +++ b/openapi/mv-openapi-root.yaml @@ -5,7 +5,7 @@ info: version: 1.0.1-oas3 termsOfService: 'https://github.com/MieuxVoter' contact: - name: Mieux Voter app developpers team + name: Mieux Voter App Development Team email: app@mieuxvoter.fr servers: - url: 'https://api.mieuxvoter.fr/v1' From 5c9f9982a751635c6dd143f688b0542a3b68726f Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 08:34:42 +0200 Subject: [PATCH 09/40] docs: add links to the README --- README.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index d1eb30c..0340d38 100644 --- a/README.md +++ b/README.md @@ -5,18 +5,21 @@ a Majority Judgment polling application spearheaded by the french nonprofit [MieuxVoter.fr](https://mieuxvoter.fr). +- API (Prod) : https://api.mieuxvoter.fr/v1 +- Sandbox : https://sandboxapi.mieuxvoter.fr/v1 + + ## TODO - [x] Draft a spec +- [ ] Use the spec +- [ ] Tweak the spec +- [x] Link to generated doc/sandbox - [ ] CI on Jenkins -- [ ] Link to generated doc/sandbox - [ ] Localization (how?) - [ ] … ------ - - ## Working on your OpenAPI Definition ### Install @@ -38,10 +41,10 @@ Validates the definition. ## Contribution Guide -Below is a sample contribution guide. The tools -in the repository don't restrict you to any +Below is a sample contribution guide. The tools +in the repository don't restrict you to any specific structure. Adjust the contribution guide -to match your own structure. However, if you +to match your own structure. However, if you don't have a structure in mind, this is a good place to start. @@ -50,7 +53,7 @@ adjust the file/folder organization. The `.redocly.yaml` controls settings for various tools including the lint tool and the reference -docs engine. Open it to find examples and +docs engine. Open it to find examples and [read the docs](https://docs.redoc.ly/cli/configuration/) for more information. From 38c5008183976de8168e3a2db9093f0a29125a0e Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 08:35:15 +0200 Subject: [PATCH 10/40] feat: add UUIDs to polls --- openapi/components/schemas/poll.yaml | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/openapi/components/schemas/poll.yaml b/openapi/components/schemas/poll.yaml index 0684620..a981f69 100644 --- a/openapi/components/schemas/poll.yaml +++ b/openapi/components/schemas/poll.yaml @@ -5,14 +5,26 @@ properties: description: A unique identifier. example: 1jDe1e5eF_IkaYPuoIYX readOnly: true + uuid: + type: string + format: uuid + description: > + A Universally Unique IDentifier for the poll. (version 4) + example: bb788552-727d-470b-827e-d7796248d293 + readOnly: true title: type: string + description: The title of the poll. 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: + description: > + A lengthy description of the poll. + In here should be stated the constitutive details of the poll, + whether it is informative or imperative for example. + example: > + This poll will help decide which projects get the most attention and budget + so you should consider the proposals carefully and with gumption. proposals: type: array description: The proposals being voted in a poll. From 5fcce977c6a7abdf4787c032ee5ada0aa921ea3a Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 08:35:52 +0200 Subject: [PATCH 11/40] chore: npm lint --- package-lock.json | 2 +- package.json | 14 +++++++++++++- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/package-lock.json b/package-lock.json index 3cca84a..5abfb4f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,5 +1,5 @@ { - "name": "mieux-voter", + "name": "mieux-voter-openapi", "version": "1.0.0", "lockfileVersion": 1, "requires": true, diff --git a/package.json b/package.json index 680007b..96dd09f 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,19 @@ "name": "mieux-voter-openapi", "version": "1.0.0", "description": "OpenAPI specifications for a Majority Judgment polling application made by MieuxVoter.fr", - "keywords": ["majority", "judgment", "poll", "polling", "api", "rest", "openapi", "democracy", "vote", "libre", "open"], + "keywords": [ + "majority", + "judgment", + "poll", + "polling", + "api", + "rest", + "openapi", + "democracy", + "vote", + "libre", + "open" + ], "homepage": "https://github.com/MieuxVoter/mv-api-spec", "bugs": "https://github.com/MieuxVoter/mv-api-spec/issues", "repository": { From 11c3832efbac607dc3f294739ad7e2a1f3bba97a Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 08:36:20 +0200 Subject: [PATCH 12/40] docs: review proposals --- openapi/components/schemas/proposal.yaml | 26 ++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/openapi/components/schemas/proposal.yaml b/openapi/components/schemas/proposal.yaml index 0c6888e..bdd788e 100644 --- a/openapi/components/schemas/proposal.yaml +++ b/openapi/components/schemas/proposal.yaml @@ -3,26 +3,36 @@ type: object properties: id: - type: integer - description: A unique identifier for the proposal, in the poll. readOnly: true + type: integer + description: > + A unique identifier for the proposal, in the context of the poll. + This is not a globally unique identifier. example: 4 uuid: - type: uuid - description: A Universally Unique IDentifier for the proposal. (version 4) readOnly: true - example: bb788552-727d-470b-827e-d7796248d293 + type: string + format: uuid + description: > + A Universally Unique IDentifier for the proposal. (UUIDv4) + example: fa888652-727e-470b-817e-d77862a8d112 name: type: string - description: Unique but short name of the proposal. + description: > + Unique but short name of the proposal. + No markup is allowed. example: A new school description: type: string - description: An optional description of the proposal. (no markup allowed) + description: > + An optional, multiline description of the proposal. + Commonmark markdown is allowed. example: This school would welcome 500 pupils. ballots: type: array - description: The ballots received by this proposal. + description: > + The ballots received by this proposal. + Each participant may emit one ballot (one judgment) per proposal. items: $ref: ./ballot.yaml From 946e99676fc005817f7c43ced647720035f3c9d0 Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 08:39:55 +0200 Subject: [PATCH 13/40] feat: add a pattern to UUID as well --- openapi/components/schemas/poll.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/openapi/components/schemas/poll.yaml b/openapi/components/schemas/poll.yaml index a981f69..5583138 100644 --- a/openapi/components/schemas/poll.yaml +++ b/openapi/components/schemas/poll.yaml @@ -1,4 +1,5 @@ type: object + properties: id: type: string @@ -8,6 +9,8 @@ properties: uuid: type: string format: uuid + # pattern is defined for implementations that don't understand format: uuid + pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' description: > A Universally Unique IDentifier for the poll. (version 4) example: bb788552-727d-470b-827e-d7796248d293 From 9c66f787125fe70d8705f652f192539fb5ee9c9b Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 09:25:41 +0200 Subject: [PATCH 14/40] docs: add a basic description of the API, as a markdown file --- openapi/DESCRIPTION.md | 35 +++++++++++++++++++++++++++++++++++ openapi/mv-openapi-root.yaml | 5 +++-- 2 files changed, 38 insertions(+), 2 deletions(-) create mode 100644 openapi/DESCRIPTION.md diff --git a/openapi/DESCRIPTION.md b/openapi/DESCRIPTION.md new file mode 100644 index 0000000..0ed05cf --- /dev/null +++ b/openapi/DESCRIPTION.md @@ -0,0 +1,35 @@ +## What is this? + +An _Application Programming Interface_ (API) for a polling application +using **Majority Judgment**. + +You are looking at the specifications of the communication between server and clients, usually because you want to make your own client. + +### Help, I'm lost! + +Best head to the official application client, then: +[Application MieuxVoter](https://app.mieuxvoter.fr). +See you there ! + + +## What is Majority Judgment? + +We believe that it is the most elegant polling system that is available right now. + +It was discovered in 2002 by 🇫🇷 french researchers, and it comes from 🍷 wine 🏆 contests. + + +## Contributing + +### I've found a bug! + +Head over to our [issues tracker](https://github.com/MieuxVoter/mv-api-spec/issues) with your ideas and contributions. + +### But I don't understand code! + +It's okay, we need everyone! +There's lots you can do to help, such as translating, documenting, reporting issues, painting pixels, promoting majority judgment… + +### Shut up and take my money! + +Donations help us boost development : [Donate](https://mieuxvoter.fr/index.php/participer/). diff --git a/openapi/mv-openapi-root.yaml b/openapi/mv-openapi-root.yaml index 95e5a20..2b10b24 100644 --- a/openapi/mv-openapi-root.yaml +++ b/openapi/mv-openapi-root.yaml @@ -1,7 +1,8 @@ openapi: 3.0.0 info: - title: Mieux Voter - description: A poll application based on Majority Judgment. + title: API Mieux Voter + description: + $ref: 'DESCRIPTION.md' version: 1.0.1-oas3 termsOfService: 'https://github.com/MieuxVoter' contact: From 0a35b20881c57aabcfada42fd68c42cba78cec2a Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 10:39:25 +0200 Subject: [PATCH 15/40] docs: review the participants --- openapi/components/schemas/participant.yaml | 23 ++++++++++++--------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/openapi/components/schemas/participant.yaml b/openapi/components/schemas/participant.yaml index 05d7f1b..2c3d6e4 100644 --- a/openapi/components/schemas/participant.yaml +++ b/openapi/components/schemas/participant.yaml @@ -1,17 +1,23 @@ type: object properties: id: + readOnly: true type: string description: A unique identifier. example: JtRm05yjMAuFCI2uwnFp - readOnly: true - description: + name: + type: string + maxLength: 32 + description: An optional name or pseudonym for the participant. + example: Jane Doe + email: type: string - description: An optional description of the participant. - example: John Doe - has-participed: + description: > + The electronic mail address that will eventually be created at the creation of the participant (not kept in memory). + example: jane.doe@example.com + has-participated: type: boolean - description: True if the participant already participed to the poll, False otherwise. + description: True if the participant already participated to the poll, False otherwise example: true poll-id: type: string @@ -21,9 +27,6 @@ properties: 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 From b59926d71690fc8be8cd2a8026f9ca6fce763cfd Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 10:51:19 +0200 Subject: [PATCH 16/40] docs: describe polls, using a markdown file --- openapi/components/schemas/poll.md | 2 ++ openapi/components/schemas/poll.yaml | 7 +++++-- 2 files changed, 7 insertions(+), 2 deletions(-) create mode 100644 openapi/components/schemas/poll.md diff --git a/openapi/components/schemas/poll.md b/openapi/components/schemas/poll.md new file mode 100644 index 0000000..bba9cf7 --- /dev/null +++ b/openapi/components/schemas/poll.md @@ -0,0 +1,2 @@ +A `Poll` is the core model of the application. +A `Poll` exposes a list of `Proposal`s, and `Participant`s may individually give each `Proposal` a `Grade`. (in a `Ballot`) diff --git a/openapi/components/schemas/poll.yaml b/openapi/components/schemas/poll.yaml index 5583138..18566fe 100644 --- a/openapi/components/schemas/poll.yaml +++ b/openapi/components/schemas/poll.yaml @@ -1,5 +1,6 @@ type: object - +description: + $ref: 'poll.md' properties: id: type: string @@ -30,7 +31,9 @@ properties: so you should consider the proposals carefully and with gumption. proposals: type: array - description: The proposals being voted in a poll. + description: > + The proposals being judged by the participants in a poll. + It makes no sense to have less than two proposals in a poll. minItems: 2 maxItems: 20 items: From 4cd2fd1375a5e3b5bbb710018c6d66834b4a0d74 Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 10:56:09 +0200 Subject: [PATCH 17/40] chore(build) --- README.md | 2 +- mv-openapi.yaml | 134 +++++++++++++++++++++++++++++++----------------- 2 files changed, 87 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 0340d38..86cb4d4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Mieux Voter OpenAPI Definition -This reposority hosts the OpenAPI specification for the API of MieuxVoter, +This reposority hosts the **OpenAPI specifications** for the API of MieuxVoter, a Majority Judgment polling application spearheaded by the french nonprofit [MieuxVoter.fr](https://mieuxvoter.fr). diff --git a/mv-openapi.yaml b/mv-openapi.yaml index 30ddd3b..500c6b5 100644 --- a/mv-openapi.yaml +++ b/mv-openapi.yaml @@ -1,12 +1,12 @@ # 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. + title: API Mieux Voter + description: "## What is this?\n\nAn _Application Programming Interface_ (API) for a polling application\nusing **Majority Judgment**.\n\nYou are looking at the specifications of the communication between server and clients, usually because you want to make your own client.\n\n### Help, I'm lost!\n\nBest head to the official application client, then:\n[Application MieuxVoter](https://app.mieuxvoter.fr).\nSee you there !\n\n\n## What is Majority Judgment?\n\nWe believe that it is the most elegant polling system that is available right now.\n\nIt was discovered in 2002 by \U0001F1EB\U0001F1F7 french researchers, and it comes from \U0001F377 wine \U0001F3C6 contests.\n\n\n## Contributing\n\n### I've found a bug!\n\nHead over to our [issues tracker](https://github.com/MieuxVoter/mv-api-spec/issues) with your ideas and contributions.\n\n### But I don't understand code!\n\nIt's okay, we need everyone!\nThere's lots you can do to help, such as translating, documenting, reporting issues, painting pixels, promoting majority judgment…\n\n### Shut up and take my money!\n\nDonations help us boost development : [Donate](https://mieuxvoter.fr/index.php/participer/).\n" version: 1.0.1-oas3 termsOfService: 'https://github.com/MieuxVoter' contact: - name: Mieux Voter app developpers team + name: Mieux Voter App Development Team email: app@mieuxvoter.fr servers: - url: 'https://api.mieuxvoter.fr/v1' @@ -367,72 +367,95 @@ components: description: A unique identifier example: 4 readOnly: true - mention: + grade: type: integer - description: >- - The mention item, according to the mentions array defined when - creating the poll. + description: > + One grade of the grading defined when creating the poll. Zero (0) + means the worst grade, and it goes upwards from there, up to the + size of the grading, minus one. example: 2 proposal: type: object properties: id: - type: integer - description: A unique identifier. readOnly: true + type: integer + description: > + A unique identifier for the proposal, in the context of the poll. + This is not a globally unique identifier. example: 4 + uuid: + readOnly: true + type: string + format: uuid + description: | + A Universally Unique IDentifier for the proposal. (UUIDv4) + example: fa888652-727e-470b-817e-d77862a8d112 name: type: string - description: Unique but short name of the proposal. + description: | + Unique but short name of the proposal. No markup is allowed. example: A new school + description: + type: string + description: > + An optional, multiline description of the proposal. Commonmark + markdown is allowed. + example: This school would welcome 500 pupils. ballots: type: array - description: The ballots received by this proposal. + description: > + The ballots received by this proposal. Each participant may emit one + ballot (one judgment) per 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: + grade: type: object properties: id: type: integer - description: A unique identifier + description: > + Unique identifier of the grade in its grading. Zero (0) is the worst + grade, and it goes upwards. example: 0 readOnly: true name: type: string - description: >- - Unique but short name of the mention, like *Excellent* or *To - reject*. - example: Excellent + description: | + Unique but short name of the grade, like "Excellent" or "To reject". + example: Good description: type: string - description: An optional description of the mention - example: 'In this poll, the mention *To reject* disqualifies the proposal.' + description: An optional description of the grade. + example: 'In this poll, the grade "To reject" disqualifies the proposal.' required: - name participant: type: object properties: id: + readOnly: true type: string description: A unique identifier. example: JtRm05yjMAuFCI2uwnFp - readOnly: true - description: + name: + type: string + maxLength: 32 + description: An optional name or pseudonym for the participant. + example: Jane Doe + email: type: string - description: An optional description of the participant. - example: John Doe - has-participed: + description: > + The electronic mail address that will eventually be created at the + creation of the participant (not kept in memory). + example: jane.doe@example.com + has-participated: type: boolean description: >- - True if the participant already participed to the poll, False - otherwise. + True if the participant already participated to the poll, False + otherwise example: true poll-id: type: string @@ -442,44 +465,59 @@ components: 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 + description: > + A `Poll` is the core model of the application. + + A `Poll` exposes a list of `Proposal`s, and `Participant`s may + individually give each `Proposal` a `Grade`. (in a `Ballot`) properties: id: type: string - description: A unique identifier + description: A unique identifier. example: 1jDe1e5eF_IkaYPuoIYX readOnly: true + uuid: + type: string + format: uuid + pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' + description: | + A Universally Unique IDentifier for the poll. (version 4) + example: bb788552-727d-470b-827e-d7796248d293 + readOnly: true title: type: string + description: The title of the poll. 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 + description: > + A lengthy description of the poll. In here should be stated the + constitutive details of the poll, whether it is informative or + imperative for example. + example: > + This poll will help decide which projects get the most attention and + budget so you should consider the proposals carefully and with + gumption. proposals: type: array - description: The proposals being voted in a poll. + description: > + The proposals being judged by the participants in a poll. It makes + no sense to have less than two proposals in a poll. minItems: 2 maxItems: 20 items: $ref: '#/components/schemas/proposal' - mentions: + grades: type: array - description: The mentions on which one participant vote to a proposal. + description: The grades on which one participant vote to a proposal. minItems: 2 maxItems: 10 items: - $ref: '#/components/schemas/mention' + $ref: '#/components/schemas/grade' participants: type: array description: The participants that are allowed to participate to the election. @@ -490,7 +528,7 @@ components: 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.' + description: 'True if anyone can participate in this poll, False otherwise.' example: false required: - title @@ -517,9 +555,9 @@ components: 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. + An array representing grades level for each proposal, according to + the grades list, following the order of the proposals array defined + when the related poll has been created. example: - 0 - 6 From 5c20b56d824b05a22cd009bac79f11f64c78db0c Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 11:32:05 +0200 Subject: [PATCH 18/40] fix: updating a poll should return the poll, not an array --- openapi/paths/polls@{poll-id}.yaml | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/openapi/paths/polls@{poll-id}.yaml b/openapi/paths/polls@{poll-id}.yaml index 2e575d0..0133dfb 100644 --- a/openapi/paths/polls@{poll-id}.yaml +++ b/openapi/paths/polls@{poll-id}.yaml @@ -7,7 +7,7 @@ parameters: format: int64 get: operationId: get-poll - summary: Gets a poll by ID + summary: Gets a poll by ID. responses: '200': description: OK @@ -19,7 +19,7 @@ get: $ref: ../components/responses/poll-not-found.yaml patch: operationId: update-poll - summary: Updates a poll + summary: Updates a poll. requestBody: required: true content: @@ -31,19 +31,23 @@ patch: - pollAuth: [] responses: '200': - description: OK + description: Poll was updated. content: application/json: schema: - type: array - items: - $ref: ../components/schemas/poll.yaml + $ref: ../components/schemas/poll.yaml + '404': + $ref: ../components/responses/poll-not-found.yaml delete: operationId: delete-poll - summary: Deletes a poll + summary: Deletes a poll. + description: > + All the Poll data will be permanently erased. + This includes all the corollary models (Tally, Ballots, …) + Only the Poll's author may delete it. (and wild admins) responses: '200': - description: OK + description: Poll was deleted. '404': $ref: ../components/responses/poll-not-found.yaml security: From efc90c2738ddfea4694508d3bb2dcdb46a239bd3 Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 15:07:18 +0200 Subject: [PATCH 19/40] fix: summaries should not end with a dot (I looks better in the generated doc, and summaries should be one-liners anyway. Use description instead for longer sentences. --- openapi/paths/polls.yaml | 6 +++--- openapi/paths/polls@{poll-id}.yaml | 6 +++--- openapi/paths/polls@{poll-id}@participants.yaml | 4 ++-- .../polls@{poll-id}@participants@{participant-id}@.yaml | 4 ++-- openapi/paths/polls@{poll-id}@results.yaml | 2 +- 5 files changed, 11 insertions(+), 11 deletions(-) diff --git a/openapi/paths/polls.yaml b/openapi/paths/polls.yaml index cbd1523..3eecf43 100644 --- a/openapi/paths/polls.yaml +++ b/openapi/paths/polls.yaml @@ -1,6 +1,6 @@ get: operationId: get-polls - summary: Gets all polls. + summary: Gets all polls responses: '200': description: OK @@ -12,7 +12,7 @@ get: $ref: ../components/schemas/poll.yaml post: operationId: create-poll - summary: Creates a poll. + summary: Creates a poll requestBody: required: true content: @@ -42,4 +42,4 @@ post: list-poll-results: $ref: ../components/links/list-poll-results.yaml '400': - description: Bad Request. Expect at least 2 proposals and a title. + description: Bad Request. Provide at least 2 proposals and a title. diff --git a/openapi/paths/polls@{poll-id}.yaml b/openapi/paths/polls@{poll-id}.yaml index 0133dfb..2420028 100644 --- a/openapi/paths/polls@{poll-id}.yaml +++ b/openapi/paths/polls@{poll-id}.yaml @@ -7,7 +7,7 @@ parameters: format: int64 get: operationId: get-poll - summary: Gets a poll by ID. + summary: Gets a poll by ID responses: '200': description: OK @@ -19,7 +19,7 @@ get: $ref: ../components/responses/poll-not-found.yaml patch: operationId: update-poll - summary: Updates a poll. + summary: Updates a poll requestBody: required: true content: @@ -40,7 +40,7 @@ patch: $ref: ../components/responses/poll-not-found.yaml delete: operationId: delete-poll - summary: Deletes a poll. + summary: Deletes a poll description: > All the Poll data will be permanently erased. This includes all the corollary models (Tally, Ballots, …) diff --git a/openapi/paths/polls@{poll-id}@participants.yaml b/openapi/paths/polls@{poll-id}@participants.yaml index bc18c27..f4c3dd8 100644 --- a/openapi/paths/polls@{poll-id}@participants.yaml +++ b/openapi/paths/polls@{poll-id}@participants.yaml @@ -6,7 +6,7 @@ parameters: type: string post: operationId: add-participant-to-poll - description: Add a participant to a poll + summary: Adds a participant to a poll requestBody: content: application/json: @@ -14,7 +14,7 @@ post: $ref: ../components/schemas/participant.yaml responses: '200': - description: Invitation was sent + description: Invitation was sent. content: text/plain: schema: diff --git a/openapi/paths/polls@{poll-id}@participants@{participant-id}@.yaml b/openapi/paths/polls@{poll-id}@participants@{participant-id}@.yaml index 5bdbca0..e92ca49 100644 --- a/openapi/paths/polls@{poll-id}@participants@{participant-id}@.yaml +++ b/openapi/paths/polls@{poll-id}@participants@{participant-id}@.yaml @@ -6,7 +6,7 @@ parameters: type: string get: operationId: get-poll-participant - summary: Get a participant from a poll + summary: Gets a participant from a poll responses: '200': description: OK @@ -21,7 +21,7 @@ get: - pollAuth: [] delete: operationId: delete-poll-participant - summary: Delete a participant from a poll + summary: Deletes a participant from a poll responses: '200': description: OK diff --git a/openapi/paths/polls@{poll-id}@results.yaml b/openapi/paths/polls@{poll-id}@results.yaml index 8746428..1932b76 100644 --- a/openapi/paths/polls@{poll-id}@results.yaml +++ b/openapi/paths/polls@{poll-id}@results.yaml @@ -6,7 +6,7 @@ parameters: type: string get: operationId: get-poll-results - description: Get results of a poll + summary: Gets results of a poll responses: '200': description: OK From 1d331fef803fcef4c3c4bedb4343606c64398b52 Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 15:07:55 +0200 Subject: [PATCH 20/40] chore(build) --- mv-openapi.yaml | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/mv-openapi.yaml b/mv-openapi.yaml index 500c6b5..e767afb 100644 --- a/mv-openapi.yaml +++ b/mv-openapi.yaml @@ -17,7 +17,7 @@ paths: /polls: get: operationId: get-polls - summary: Gets all polls. + summary: Gets all polls responses: '200': description: OK @@ -29,7 +29,7 @@ paths: $ref: '#/components/schemas/poll' post: operationId: create-poll - summary: Creates a poll. + summary: Creates a poll requestBody: required: true content: @@ -59,7 +59,7 @@ paths: list-poll-results: $ref: '#/components/links/list-poll-results' '400': - description: Bad Request. Expect at least 2 proposals and a title. + description: Bad Request. Provide at least 2 proposals and a title. '/polls/{poll-id}': parameters: - in: path @@ -94,19 +94,23 @@ paths: - pollAuth: [] responses: '200': - description: OK + description: Poll was updated. content: application/json: schema: - type: array - items: - $ref: '#/components/schemas/poll' + $ref: '#/components/schemas/poll' + '404': + $ref: '#/components/responses/poll-not-found' delete: operationId: delete-poll summary: Deletes a poll + description: > + All the Poll data will be permanently erased. This includes all the + corollary models (Tally, Ballots, …) Only the Poll's author may delete + it. (and wild admins) responses: '200': - description: OK + description: Poll was deleted. '404': $ref: '#/components/responses/poll-not-found' security: @@ -187,7 +191,7 @@ paths: type: string post: operationId: add-participant-to-poll - description: Add a participant to a poll + summary: Adds a participant to a poll requestBody: content: application/json: @@ -195,7 +199,7 @@ paths: $ref: '#/components/schemas/participant' responses: '200': - description: Invitation was sent + description: Invitation was sent. content: text/plain: schema: @@ -211,7 +215,7 @@ paths: type: string get: operationId: get-poll-participant - summary: Get a participant from a poll + summary: Gets a participant from a poll responses: '200': description: OK @@ -226,7 +230,7 @@ paths: - pollAuth: [] delete: operationId: delete-poll-participant - summary: Delete a participant from a poll + summary: Deletes a participant from a poll responses: '200': description: OK @@ -243,7 +247,7 @@ paths: type: string get: operationId: get-poll-results - description: Get results of a poll + summary: Gets results of a poll responses: '200': description: OK From 1c165637c6c70da33c4e0d1bdae7f1420279a6ee Mon Sep 17 00:00:00 2001 From: domi41 Date: Sun, 6 Sep 2020 23:43:10 +0200 Subject: [PATCH 21/40] docs: review the responses --- openapi/components/responses/ballot-not-found.yaml | 2 +- openapi/components/responses/participant-not-found.yaml | 2 +- openapi/components/responses/poll-not-found.yaml | 2 +- openapi/components/responses/unauthorized.yaml | 4 +++- 4 files changed, 6 insertions(+), 4 deletions(-) diff --git a/openapi/components/responses/ballot-not-found.yaml b/openapi/components/responses/ballot-not-found.yaml index e98c180..096bf0a 100644 --- a/openapi/components/responses/ballot-not-found.yaml +++ b/openapi/components/responses/ballot-not-found.yaml @@ -1,4 +1,4 @@ -description: The specified ballot was not found +description: The requested ballot was not found. content: application/json: schema: diff --git a/openapi/components/responses/participant-not-found.yaml b/openapi/components/responses/participant-not-found.yaml index 8e7e0dd..4d6649e 100644 --- a/openapi/components/responses/participant-not-found.yaml +++ b/openapi/components/responses/participant-not-found.yaml @@ -1,4 +1,4 @@ -description: The specified participant was not found +description: The requested participant was not found. content: application/json: schema: diff --git a/openapi/components/responses/poll-not-found.yaml b/openapi/components/responses/poll-not-found.yaml index 70684dd..55977ca 100644 --- a/openapi/components/responses/poll-not-found.yaml +++ b/openapi/components/responses/poll-not-found.yaml @@ -1,4 +1,4 @@ -description: The specified poll was not found +description: The requested poll was not found. content: application/json: schema: diff --git a/openapi/components/responses/unauthorized.yaml b/openapi/components/responses/unauthorized.yaml index 15dba9b..953a85a 100644 --- a/openapi/components/responses/unauthorized.yaml +++ b/openapi/components/responses/unauthorized.yaml @@ -1,4 +1,6 @@ -description: Unauthorized +description: > + Your are not authorized to do that operation. + Try logging in? If the problem persists, contact an administrator. content: application/json: schema: From 42b81d5e9116f728a4309faf91722183a7715bdd Mon Sep 17 00:00:00 2001 From: domi41 Date: Mon, 7 Sep 2020 00:25:28 +0200 Subject: [PATCH 22/40] docs: review the poll --- openapi/components/schemas/poll.yaml | 48 ++++++++++++++++++++-------- 1 file changed, 35 insertions(+), 13 deletions(-) diff --git a/openapi/components/schemas/poll.yaml b/openapi/components/schemas/poll.yaml index 18566fe..db456ea 100644 --- a/openapi/components/schemas/poll.yaml +++ b/openapi/components/schemas/poll.yaml @@ -3,19 +3,23 @@ description: $ref: 'poll.md' properties: id: - type: string - description: A unique identifier. - example: 1jDe1e5eF_IkaYPuoIYX readOnly: true - uuid: type: string - format: uuid - # pattern is defined for implementations that don't understand format: uuid - pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' - description: > - A Universally Unique IDentifier for the poll. (version 4) - example: bb788552-727d-470b-827e-d7796248d293 - readOnly: true + description: | + A unique identifier for the poll. + That identifier has a fixed length of 20 alphanumerical characters, + including some special characters like `_`. + pattern: '[0-9a-fA-F_]{20}' + example: 1jDe1e5eF_IkaYPuoIYX +# uuid: +# readOnly: true +# type: string +# format: uuid +# # pattern is defined for implementations that don't understand format: uuid +# pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' +# description: > +# A Universally Unique IDentifier for the poll. (version 4) +# example: bb788552-727d-470b-827e-d7796248d293 title: type: string description: The title of the poll. @@ -40,14 +44,32 @@ properties: $ref: ./proposal.yaml grades: type: array - description: The grades on which one participant vote to a proposal. + description: | + The grades that participants may give to each proposal. + The grades should be **non-ambiguously ordinal**, + ie. their ranking should be obvious to everyone. + + #### Good examples + - DISAPPROVED, APPROVED + - TO REJECT, POOR, PASSABLE, GOOD, VERY GOOD, EXCELLENT + - BORING, ENTERTAINING, FUN, AMAZING (to be discussed) + + #### Bad examples + - LOUSY, MEDIOCRE, OKAY, GOOD, FINE, PEACHY + - BORING, BEAUTIFUL, FUN, MAGNIFICIENT minItems: 2 maxItems: 10 items: $ref: ./grade.yaml participants: type: array - description: The participants that are allowed to participate to the election. + description: | + The participants that are allowed to participate in the poll. + That property is ignored if `restrict_participants` is `false`. + + --- + + Or should this be the list of the participants of the poll? items: $ref: ./participant.yaml user-id: From e6cfe1cf8afb8be271906e65ef33fb6102ff3439 Mon Sep 17 00:00:00 2001 From: domi41 Date: Mon, 7 Sep 2020 03:04:45 +0200 Subject: [PATCH 23/40] chore(lint) --- openapi/components/schemas/result.yaml | 3 ++- openapi/paths/polls@{poll-id}@results.yaml | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/openapi/components/schemas/result.yaml b/openapi/components/schemas/result.yaml index c2b6bd3..5f7829b 100644 --- a/openapi/components/schemas/result.yaml +++ b/openapi/components/schemas/result.yaml @@ -4,7 +4,8 @@ properties: $ref: ./poll.yaml ranking: type: array - description: An array representing grades level for each proposal, + description: | + An array representing grades level for each proposal, according to the grades list, following the order of the proposals array defined when the related poll has been created. example: [0, 6, 3, 2, 2] diff --git a/openapi/paths/polls@{poll-id}@results.yaml b/openapi/paths/polls@{poll-id}@results.yaml index 1932b76..108f37a 100644 --- a/openapi/paths/polls@{poll-id}@results.yaml +++ b/openapi/paths/polls@{poll-id}@results.yaml @@ -6,7 +6,7 @@ parameters: type: string get: operationId: get-poll-results - summary: Gets results of a poll + summary: Gets the results of a poll responses: '200': description: OK From 81d86be3b806869db66bf96a8720aded5b168890 Mon Sep 17 00:00:00 2001 From: domi41 Date: Thu, 24 Sep 2020 12:33:14 +0200 Subject: [PATCH 24/40] chore: ending dots --- openapi/components/schemas/error.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/openapi/components/schemas/error.yaml b/openapi/components/schemas/error.yaml index 24bdbcd..a00b44f 100644 --- a/openapi/components/schemas/error.yaml +++ b/openapi/components/schemas/error.yaml @@ -2,12 +2,12 @@ type: object properties: code: type: string - description: The HTTP code of the response + description: The HTTP code of the response. example: 404 message: type: string - description: The response details - example: The specified participant was not found + description: The response details. + example: The specified participant was not found. required: - code - message From 00b7713eb3acd88d35223d689f113b1c7fde9526 Mon Sep 17 00:00:00 2001 From: domi41 Date: Thu, 24 Sep 2020 12:33:48 +0200 Subject: [PATCH 25/40] fix: a poll has a subject --- openapi/components/schemas/poll.md | 2 +- openapi/components/schemas/poll.yaml | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/openapi/components/schemas/poll.md b/openapi/components/schemas/poll.md index bba9cf7..7a5e1cb 100644 --- a/openapi/components/schemas/poll.md +++ b/openapi/components/schemas/poll.md @@ -1,2 +1,2 @@ A `Poll` is the core model of the application. -A `Poll` exposes a list of `Proposal`s, and `Participant`s may individually give each `Proposal` a `Grade`. (in a `Ballot`) +A `Poll` has a subject exposes a list of `Proposal`s, and `Participant`s may individually give each `Proposal` a `Grade`. (in a `Ballot`) diff --git a/openapi/components/schemas/poll.yaml b/openapi/components/schemas/poll.yaml index db456ea..a3d59a9 100644 --- a/openapi/components/schemas/poll.yaml +++ b/openapi/components/schemas/poll.yaml @@ -20,9 +20,9 @@ properties: # description: > # A Universally Unique IDentifier for the poll. (version 4) # example: bb788552-727d-470b-827e-d7796248d293 - title: + subject: type: string - description: The title of the poll. + description: The subject of the poll. example: What project should our neighbourhood invest in for the next year? description: type: string @@ -36,7 +36,7 @@ properties: proposals: type: array description: > - The proposals being judged by the participants in a poll. + The proposals being judged by the participants of the poll. It makes no sense to have less than two proposals in a poll. minItems: 2 maxItems: 20 @@ -79,6 +79,6 @@ properties: type: boolean description: True if anyone can participate in this poll, False otherwise. example: false -required: - - title - - proposals +# required: +# - title +# - proposals From efed66a31eb72a04b541a5b7fa158dfd49be6f3b Mon Sep 17 00:00:00 2001 From: domi41 Date: Thu, 24 Sep 2020 12:43:51 +0200 Subject: [PATCH 26/40] feat: decouple poll properties This will probably be handy with path responses, since some have requirements and others don't --- .../components/schemas/poll-properties.yaml | 77 +++++++++++++++++ openapi/components/schemas/poll.yaml | 84 +------------------ 2 files changed, 81 insertions(+), 80 deletions(-) create mode 100644 openapi/components/schemas/poll-properties.yaml diff --git a/openapi/components/schemas/poll-properties.yaml b/openapi/components/schemas/poll-properties.yaml new file mode 100644 index 0000000..5aa484e --- /dev/null +++ b/openapi/components/schemas/poll-properties.yaml @@ -0,0 +1,77 @@ +id: + readOnly: true + type: string + description: | + A unique identifier for the poll. + That identifier has a fixed length of 20 alphanumerical characters, + including some special characters like `_`. + pattern: '[0-9a-fA-F_]{20}' + example: 1jDe1e5eF_IkaYPuoIYX +# uuid: +# readOnly: true +# type: string +# format: uuid +# # pattern is defined for implementations that don't understand format: uuid +# pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' +# description: > +# A Universally Unique IDentifier for the poll. (version 4) +# example: bb788552-727d-470b-827e-d7796248d293 +subject: + type: string + description: The subject of the poll. + example: What project should our neighbourhood invest in for the next year? +description: + type: string + description: > + A lengthy description of the poll. + In here should be stated the constitutive details of the poll, + whether it is informative or imperative for example. + example: > + This poll will help decide which projects get the most attention and budget + so you should consider the proposals carefully and with gumption. +proposals: + type: array + description: > + The proposals being judged by the participants of the poll. + It makes no sense to have less than two proposals in a poll. + minItems: 2 + maxItems: 20 + items: + $ref: ./proposal.yaml +grades: + type: array + description: | + The grades that participants may give to each proposal. + The grades should be **non-ambiguously ordinal**, + ie. their ranking should be obvious to everyone. + + #### Good examples + - DISAPPROVED, APPROVED + - TO REJECT, POOR, PASSABLE, GOOD, VERY GOOD, EXCELLENT + - BORING, ENTERTAINING, FUN, AMAZING (to be discussed) + + #### Bad examples + - LOUSY, MEDIOCRE, OKAY, GOOD, FINE, PEACHY + - BORING, BEAUTIFUL, FUN, MAGNIFICIENT + minItems: 2 + maxItems: 10 + items: + $ref: ./grade.yaml +participants: + type: array + description: | + The participants that are allowed to participate in the poll. + That property is ignored if `restrict_participants` is `false`. + + --- + + Or should this be the list of the participants of the poll? + items: + $ref: ./participant.yaml +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 in this poll, False otherwise. + example: false diff --git a/openapi/components/schemas/poll.yaml b/openapi/components/schemas/poll.yaml index a3d59a9..ba52f3f 100644 --- a/openapi/components/schemas/poll.yaml +++ b/openapi/components/schemas/poll.yaml @@ -2,83 +2,7 @@ type: object description: $ref: 'poll.md' properties: - id: - readOnly: true - type: string - description: | - A unique identifier for the poll. - That identifier has a fixed length of 20 alphanumerical characters, - including some special characters like `_`. - pattern: '[0-9a-fA-F_]{20}' - example: 1jDe1e5eF_IkaYPuoIYX -# uuid: -# readOnly: true -# type: string -# format: uuid -# # pattern is defined for implementations that don't understand format: uuid -# pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' -# description: > -# A Universally Unique IDentifier for the poll. (version 4) -# example: bb788552-727d-470b-827e-d7796248d293 - subject: - type: string - description: The subject of the poll. - example: What project should our neighbourhood invest in for the next year? - description: - type: string - description: > - A lengthy description of the poll. - In here should be stated the constitutive details of the poll, - whether it is informative or imperative for example. - example: > - This poll will help decide which projects get the most attention and budget - so you should consider the proposals carefully and with gumption. - proposals: - type: array - description: > - The proposals being judged by the participants of the poll. - It makes no sense to have less than two proposals in a poll. - minItems: 2 - maxItems: 20 - items: - $ref: ./proposal.yaml - grades: - type: array - description: | - The grades that participants may give to each proposal. - The grades should be **non-ambiguously ordinal**, - ie. their ranking should be obvious to everyone. - - #### Good examples - - DISAPPROVED, APPROVED - - TO REJECT, POOR, PASSABLE, GOOD, VERY GOOD, EXCELLENT - - BORING, ENTERTAINING, FUN, AMAZING (to be discussed) - - #### Bad examples - - LOUSY, MEDIOCRE, OKAY, GOOD, FINE, PEACHY - - BORING, BEAUTIFUL, FUN, MAGNIFICIENT - minItems: 2 - maxItems: 10 - items: - $ref: ./grade.yaml - participants: - type: array - description: | - The participants that are allowed to participate in the poll. - That property is ignored if `restrict_participants` is `false`. - - --- - - Or should this be the list of the participants of the poll? - items: - $ref: ./participant.yaml - 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 in this poll, False otherwise. - example: false -# required: -# - title -# - proposals + $ref: 'poll-properties.yaml' +required: + - title + - proposals From 729ce952d8c142fdaf8d1725a3622c08062d26a7 Mon Sep 17 00:00:00 2001 From: domi41 Date: Thu, 24 Sep 2020 12:48:37 +0200 Subject: [PATCH 27/40] feat: use another schema for poll creation This is an attempt at handling the requirements --- openapi/components/schemas/poll-new.yaml | 8 ++++++++ openapi/components/schemas/poll.yaml | 3 --- openapi/paths/polls.yaml | 2 +- 3 files changed, 9 insertions(+), 4 deletions(-) create mode 100644 openapi/components/schemas/poll-new.yaml diff --git a/openapi/components/schemas/poll-new.yaml b/openapi/components/schemas/poll-new.yaml new file mode 100644 index 0000000..73ac983 --- /dev/null +++ b/openapi/components/schemas/poll-new.yaml @@ -0,0 +1,8 @@ +type: object +description: + $ref: 'poll.md' +properties: + $ref: 'poll-properties.yaml' +required: + - subject + - proposals diff --git a/openapi/components/schemas/poll.yaml b/openapi/components/schemas/poll.yaml index ba52f3f..4c921ee 100644 --- a/openapi/components/schemas/poll.yaml +++ b/openapi/components/schemas/poll.yaml @@ -3,6 +3,3 @@ description: $ref: 'poll.md' properties: $ref: 'poll-properties.yaml' -required: - - title - - proposals diff --git a/openapi/paths/polls.yaml b/openapi/paths/polls.yaml index 3eecf43..25ad15e 100644 --- a/openapi/paths/polls.yaml +++ b/openapi/paths/polls.yaml @@ -18,7 +18,7 @@ post: content: application/json: schema: - $ref: ../components/schemas/poll.yaml + $ref: ../components/schemas/poll-new.yaml responses: '201': description: Created From 492bd2a0334702e9a0e90722797dc0a728a9bd3f Mon Sep 17 00:00:00 2001 From: domi41 Date: Thu, 24 Sep 2020 13:28:04 +0200 Subject: [PATCH 28/40] feat: tag some paths --- openapi/mv-openapi-root.yaml | 7 +++++++ openapi/paths/polls.yaml | 5 +++++ openapi/paths/polls@{poll-id}.yaml | 7 +++++++ 3 files changed, 19 insertions(+) diff --git a/openapi/mv-openapi-root.yaml b/openapi/mv-openapi-root.yaml index 2b10b24..937d7e7 100644 --- a/openapi/mv-openapi-root.yaml +++ b/openapi/mv-openapi-root.yaml @@ -32,6 +32,13 @@ paths: $ref: paths/users.yaml '/users/{user-id}': $ref: 'paths/users@{user-id}.yaml' +tags: + - name: Poll Organization + description: > + Paths about the organization of polls. + - name: Poll Participation + description: > + Paths about participating to a poll. components: securitySchemes: participantAuth: diff --git a/openapi/paths/polls.yaml b/openapi/paths/polls.yaml index 25ad15e..16d213d 100644 --- a/openapi/paths/polls.yaml +++ b/openapi/paths/polls.yaml @@ -1,6 +1,9 @@ get: operationId: get-polls summary: Gets all polls + tags: + - Poll Organization + - Poll Participation responses: '200': description: OK @@ -13,6 +16,8 @@ get: post: operationId: create-poll summary: Creates a poll + tags: + - Poll Organization requestBody: required: true content: diff --git a/openapi/paths/polls@{poll-id}.yaml b/openapi/paths/polls@{poll-id}.yaml index 2420028..8c859de 100644 --- a/openapi/paths/polls@{poll-id}.yaml +++ b/openapi/paths/polls@{poll-id}.yaml @@ -8,6 +8,9 @@ parameters: get: operationId: get-poll summary: Gets a poll by ID + tags: + - Poll Organization + - Poll Participation responses: '200': description: OK @@ -20,6 +23,8 @@ get: patch: operationId: update-poll summary: Updates a poll + tags: + - Poll Organization requestBody: required: true content: @@ -45,6 +50,8 @@ delete: All the Poll data will be permanently erased. This includes all the corollary models (Tally, Ballots, …) Only the Poll's author may delete it. (and wild admins) + tags: + - Poll Organization responses: '200': description: Poll was deleted. From ed8607066c5a2f27101f69049c94da78b219c809 Mon Sep 17 00:00:00 2001 From: domi41 Date: Thu, 24 Sep 2020 14:04:32 +0200 Subject: [PATCH 29/40] feat: tag more paths --- openapi/components/schemas/grade.yaml | 1 + openapi/mv-openapi-root.yaml | 9 ++++++++- openapi/paths/polls.yaml | 1 + openapi/paths/polls@{poll-id}@ballots.yaml | 4 +++- openapi/paths/polls@{poll-id}@ballots@{ballot-id}.yaml | 5 +++++ openapi/paths/polls@{poll-id}@results.yaml | 2 ++ 6 files changed, 20 insertions(+), 2 deletions(-) diff --git a/openapi/components/schemas/grade.yaml b/openapi/components/schemas/grade.yaml index fe39a24..1ce2a68 100644 --- a/openapi/components/schemas/grade.yaml +++ b/openapi/components/schemas/grade.yaml @@ -5,6 +5,7 @@ properties: description: > Unique identifier of the grade in its grading. Zero (0) is the worst grade, and it goes upwards. + TBD - WIP example: 0 readOnly: true name: diff --git a/openapi/mv-openapi-root.yaml b/openapi/mv-openapi-root.yaml index 937d7e7..eb33b1f 100644 --- a/openapi/mv-openapi-root.yaml +++ b/openapi/mv-openapi-root.yaml @@ -33,17 +33,24 @@ paths: '/users/{user-id}': $ref: 'paths/users@{user-id}.yaml' tags: + - name: Poll Indexation + description: > + Paths about indexing (public) polls. - name: Poll Organization description: > - Paths about the organization of polls. + Paths about organizing a poll. - name: Poll Participation description: > Paths about participating to a poll. + - name: Poll Deliberation + description: > + Paths about deliberating using a poll. components: securitySchemes: participantAuth: type: http scheme: bearer + # organizerAuth pollAuth: type: http scheme: bearer diff --git a/openapi/paths/polls.yaml b/openapi/paths/polls.yaml index 16d213d..89650e7 100644 --- a/openapi/paths/polls.yaml +++ b/openapi/paths/polls.yaml @@ -2,6 +2,7 @@ get: operationId: get-polls summary: Gets all polls tags: + - Poll Indexation - Poll Organization - Poll Participation responses: diff --git a/openapi/paths/polls@{poll-id}@ballots.yaml b/openapi/paths/polls@{poll-id}@ballots.yaml index 4b44f14..146acfa 100644 --- a/openapi/paths/polls@{poll-id}@ballots.yaml +++ b/openapi/paths/polls@{poll-id}@ballots.yaml @@ -7,6 +7,8 @@ parameters: post: operationId: create-ballot summary: Creates a ballot + tags: + - Poll Participation requestBody: required: true content: @@ -26,7 +28,7 @@ post: properties: id: type: string - description: Id of the created ballot. + description: Identifier of the created ballot. links: get-ballot: $ref: ../components/links/get-ballot.yaml diff --git a/openapi/paths/polls@{poll-id}@ballots@{ballot-id}.yaml b/openapi/paths/polls@{poll-id}@ballots@{ballot-id}.yaml index e22948e..b4ac6ea 100644 --- a/openapi/paths/polls@{poll-id}@ballots@{ballot-id}.yaml +++ b/openapi/paths/polls@{poll-id}@ballots@{ballot-id}.yaml @@ -12,6 +12,9 @@ parameters: get: operationId: get-ballot summary: Gets a ballot by ID + tags: + - Poll Participation + - Poll Deliberation responses: '200': description: A ballot object @@ -22,6 +25,8 @@ get: delete: operationId: delete-ballot summary: Deletes a ballot + tags: + - Poll Participation responses: '200': description: OK diff --git a/openapi/paths/polls@{poll-id}@results.yaml b/openapi/paths/polls@{poll-id}@results.yaml index 108f37a..8aec8e0 100644 --- a/openapi/paths/polls@{poll-id}@results.yaml +++ b/openapi/paths/polls@{poll-id}@results.yaml @@ -7,6 +7,8 @@ parameters: get: operationId: get-poll-results summary: Gets the results of a poll + tags: + - Poll Deliberation responses: '200': description: OK From dcc0d48a20adba55d01817cf740c2c9916341dc1 Mon Sep 17 00:00:00 2001 From: domi41 Date: Thu, 24 Sep 2020 14:32:04 +0200 Subject: [PATCH 30/40] feat: tag user paths --- openapi/mv-openapi-root.yaml | 10 ++++++++++ openapi/paths/polls@{poll-id}@ballots@{ballot-id}.yaml | 2 +- openapi/paths/users.yaml | 9 ++++++++- openapi/paths/users@{user-id}.yaml | 6 ++++++ 4 files changed, 25 insertions(+), 2 deletions(-) diff --git a/openapi/mv-openapi-root.yaml b/openapi/mv-openapi-root.yaml index eb33b1f..b01fe42 100644 --- a/openapi/mv-openapi-root.yaml +++ b/openapi/mv-openapi-root.yaml @@ -33,6 +33,13 @@ paths: '/users/{user-id}': $ref: 'paths/users@{user-id}.yaml' tags: + - name: User Management + description: | + All the paths for: + - user creation + - authentication + - security + - trust levels - name: Poll Indexation description: > Paths about indexing (public) polls. @@ -60,3 +67,6 @@ components: userAuth: type: http scheme: bearer + adminAuth: + type: http + scheme: bearer diff --git a/openapi/paths/polls@{poll-id}@ballots@{ballot-id}.yaml b/openapi/paths/polls@{poll-id}@ballots@{ballot-id}.yaml index b4ac6ea..29fcb6e 100644 --- a/openapi/paths/polls@{poll-id}@ballots@{ballot-id}.yaml +++ b/openapi/paths/polls@{poll-id}@ballots@{ballot-id}.yaml @@ -13,8 +13,8 @@ get: operationId: get-ballot summary: Gets a ballot by ID tags: - - Poll Participation - Poll Deliberation + - Poll Participation responses: '200': description: A ballot object diff --git a/openapi/paths/users.yaml b/openapi/paths/users.yaml index f4e24e0..7076045 100644 --- a/openapi/paths/users.yaml +++ b/openapi/paths/users.yaml @@ -1,6 +1,9 @@ +# get: operationId: get-users - summary: Gets all users. + summary: Gets all users + tags: + - User Management responses: '200': description: OK @@ -10,9 +13,13 @@ get: type: array items: $ref: ../components/schemas/user.yaml + security: + - adminAuth: [] post: operationId: create-user summary: Creates an user + tags: + - User Management requestBody: required: true content: diff --git a/openapi/paths/users@{user-id}.yaml b/openapi/paths/users@{user-id}.yaml index 2cdf85a..124f77a 100644 --- a/openapi/paths/users@{user-id}.yaml +++ b/openapi/paths/users@{user-id}.yaml @@ -8,6 +8,8 @@ parameters: get: operationId: get-user summary: Gets a user by ID + tags: + - User Management responses: '200': description: OK @@ -20,6 +22,8 @@ get: patch: operationId: update-user summary: Updates a user + tags: + - User Management requestBody: required: true content: @@ -41,6 +45,8 @@ patch: delete: operationId: delete-user summary: Deletes a user + tags: + - User Management responses: '200': description: OK From 82aca33a0cb9a81a5f7a6d772854835ed249b410 Mon Sep 17 00:00:00 2001 From: domi41 Date: Thu, 24 Sep 2020 15:07:31 +0200 Subject: [PATCH 31/40] chore: review participants Participants will be re-modeled as Invitations --- openapi/components/schemas/participant.md | 4 ++++ openapi/components/schemas/participant.yaml | 2 ++ openapi/components/schemas/poll-properties.yaml | 9 --------- 3 files changed, 6 insertions(+), 9 deletions(-) create mode 100644 openapi/components/schemas/participant.md diff --git a/openapi/components/schemas/participant.md b/openapi/components/schemas/participant.md new file mode 100644 index 0000000..b4f2a7b --- /dev/null +++ b/openapi/components/schemas/participant.md @@ -0,0 +1,4 @@ + +Invitation to participate + +Poll participants are the actual users that participated. diff --git a/openapi/components/schemas/participant.yaml b/openapi/components/schemas/participant.yaml index 2c3d6e4..6fb7ace 100644 --- a/openapi/components/schemas/participant.yaml +++ b/openapi/components/schemas/participant.yaml @@ -1,4 +1,6 @@ type: object +description: + $ref: 'participant.md' properties: id: readOnly: true diff --git a/openapi/components/schemas/poll-properties.yaml b/openapi/components/schemas/poll-properties.yaml index 5aa484e..e9c2874 100644 --- a/openapi/components/schemas/poll-properties.yaml +++ b/openapi/components/schemas/poll-properties.yaml @@ -7,15 +7,6 @@ id: including some special characters like `_`. pattern: '[0-9a-fA-F_]{20}' example: 1jDe1e5eF_IkaYPuoIYX -# uuid: -# readOnly: true -# type: string -# format: uuid -# # pattern is defined for implementations that don't understand format: uuid -# pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' -# description: > -# A Universally Unique IDentifier for the poll. (version 4) -# example: bb788552-727d-470b-827e-d7796248d293 subject: type: string description: The subject of the poll. From be734cd8900ca24199ca4911b6ba8fa0561dc8d4 Mon Sep 17 00:00:00 2001 From: domi41 Date: Thu, 24 Sep 2020 21:28:45 +0200 Subject: [PATCH 32/40] docs: review users --- openapi/components/schemas/user.yaml | 33 +++++++++++++++++++--------- 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/openapi/components/schemas/user.yaml b/openapi/components/schemas/user.yaml index 2a46796..b9b60e0 100644 --- a/openapi/components/schemas/user.yaml +++ b/openapi/components/schemas/user.yaml @@ -1,15 +1,28 @@ +# Whether you participate or organize, you're a 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: + description: | + A unique identifier. + That identifier has a fixed length of 10 alphanumerical characters, + as well as `_` and `-`. + pattern: '[abcdefghijkmnopqrstuvwxyzABCDEFGHIJKLMNPQRSTUVWXYZ0-9_-]{10}' + example: 1jDe2e57_F + username: 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 + # To support all unicode letters, can we use `\p{L}` instead? + pattern: '[a-zA-Z0-9._-]{3,21}' + description: > + Unique username, chosen by the user. + May only contain alphanumeric latin characters without diacritics and `.`, `-` or `_`. + example: john.doe.41 + password: + type: string + format: password + description: > + Hash of the password chosen by the user. + # 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 From 40fdf1155a028683f7c857843fccacbb13daf8fd Mon Sep 17 00:00:00 2001 From: domi41 Date: Sat, 26 Sep 2020 15:36:42 +0200 Subject: [PATCH 33/40] docs --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 86cb4d4..8265385 100644 --- a/README.md +++ b/README.md @@ -5,16 +5,21 @@ a Majority Judgment polling application spearheaded by the french nonprofit [MieuxVoter.fr](https://mieuxvoter.fr). +- APP (Prod) : https://app.mieuxvoter.fr - API (Prod) : https://api.mieuxvoter.fr/v1 - Sandbox : https://sandboxapi.mieuxvoter.fr/v1 +## Goal + +… + + ## TODO - [x] Draft a spec - [ ] Use the spec - [ ] Tweak the spec -- [x] Link to generated doc/sandbox - [ ] CI on Jenkins - [ ] Localization (how?) - [ ] … From 5d584998b1c2193226f5e94b54a5de65e4f99e43 Mon Sep 17 00:00:00 2001 From: domi41 Date: Sat, 26 Sep 2020 15:37:16 +0200 Subject: [PATCH 34/40] docs: review the ballots --- openapi/components/schemas/ballot.md | 8 ++++++++ openapi/components/schemas/ballot.yaml | 9 ++++++++- 2 files changed, 16 insertions(+), 1 deletion(-) create mode 100644 openapi/components/schemas/ballot.md diff --git a/openapi/components/schemas/ballot.md b/openapi/components/schemas/ballot.md new file mode 100644 index 0000000..f9e9751 --- /dev/null +++ b/openapi/components/schemas/ballot.md @@ -0,0 +1,8 @@ + +A Ballot holds a single Grade given by a Participant to a Proposal of a Poll. + +A Ballot is a single Judgment. + +For security purposes, Ballots are journalized and may not be updated or deleted individually. +If you change your mind, emit a new Ballot. +It will be the responsibility of the Poll Tallier to only consider the latest ballot when there are multiple. diff --git a/openapi/components/schemas/ballot.yaml b/openapi/components/schemas/ballot.yaml index a17de99..11b2780 100644 --- a/openapi/components/schemas/ballot.yaml +++ b/openapi/components/schemas/ballot.yaml @@ -1,5 +1,8 @@ type: object +description: + $ref: ballot.md properties: + # UUIDv4, here ? id: type: integer description: A unique identifier @@ -8,7 +11,11 @@ properties: grade: type: integer description: > - One grade of the grading defined when creating the poll. + Index of a grade of the poll's grading. Zero (0) means the worst grade, and it goes upwards from there, up to the size of the grading, minus one. example: 2 + pollId: + type: string + userId: + type: string From 430fe3ee2a37493bc7ab61fbb4587dc82e14759f Mon Sep 17 00:00:00 2001 From: domi41 Date: Sat, 26 Sep 2020 15:59:32 +0200 Subject: [PATCH 35/40] docs --- openapi/components/schemas/grade.yaml | 2 +- openapi/components/schemas/poll-properties.yaml | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/openapi/components/schemas/grade.yaml b/openapi/components/schemas/grade.yaml index 1ce2a68..07b6a7b 100644 --- a/openapi/components/schemas/grade.yaml +++ b/openapi/components/schemas/grade.yaml @@ -11,7 +11,7 @@ properties: name: type: string description: > - Unique but short name of the grade, like "Excellent" or "To reject". + Unique and short name of the grade, like "Excellent" or "To reject". example: Good description: type: string diff --git a/openapi/components/schemas/poll-properties.yaml b/openapi/components/schemas/poll-properties.yaml index e9c2874..cced618 100644 --- a/openapi/components/schemas/poll-properties.yaml +++ b/openapi/components/schemas/poll-properties.yaml @@ -1,3 +1,4 @@ +# These properties are shared between poll schemes id: readOnly: true type: string From df18442d3f54da89d2a17cacfd43f0ce58f154cb Mon Sep 17 00:00:00 2001 From: domi41 Date: Thu, 8 Oct 2020 16:13:37 +0200 Subject: [PATCH 36/40] review --- openapi/components/schemas/grade.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/components/schemas/grade.yaml b/openapi/components/schemas/grade.yaml index 07b6a7b..fb28f43 100644 --- a/openapi/components/schemas/grade.yaml +++ b/openapi/components/schemas/grade.yaml @@ -11,7 +11,7 @@ properties: name: type: string description: > - Unique and short name of the grade, like "Excellent" or "To reject". + Short yet unique name of the grade, like "Excellent" or "To reject". example: Good description: type: string From 7914a739498198403ac2335c48d96cddfcc769ab Mon Sep 17 00:00:00 2001 From: domi41 Date: Fri, 9 Oct 2020 10:38:27 +0200 Subject: [PATCH 37/40] feat: bump some limits --- openapi/components/schemas/poll-properties.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/openapi/components/schemas/poll-properties.yaml b/openapi/components/schemas/poll-properties.yaml index cced618..e1e0716 100644 --- a/openapi/components/schemas/poll-properties.yaml +++ b/openapi/components/schemas/poll-properties.yaml @@ -27,7 +27,7 @@ proposals: The proposals being judged by the participants of the poll. It makes no sense to have less than two proposals in a poll. minItems: 2 - maxItems: 20 + maxItems: 256 items: $ref: ./proposal.yaml grades: @@ -46,7 +46,7 @@ grades: - LOUSY, MEDIOCRE, OKAY, GOOD, FINE, PEACHY - BORING, BEAUTIFUL, FUN, MAGNIFICIENT minItems: 2 - maxItems: 10 + maxItems: 16 items: $ref: ./grade.yaml participants: From fa295e4e8fa73d1ddf59b64ac54029c11aed8688 Mon Sep 17 00:00:00 2001 From: domi41 Date: Fri, 9 Oct 2020 10:39:17 +0200 Subject: [PATCH 38/40] docs: mention that the polls should be tagged as publicly accessible --- openapi/paths/polls.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/openapi/paths/polls.yaml b/openapi/paths/polls.yaml index 89650e7..fd9799e 100644 --- a/openapi/paths/polls.yaml +++ b/openapi/paths/polls.yaml @@ -1,10 +1,11 @@ get: operationId: get-polls summary: Gets all polls + description: | + Gets all polls that were marked as publicly accessible. + Polls only accessible by invitation or link will not be returned. tags: - Poll Indexation - - Poll Organization - - Poll Participation responses: '200': description: OK From b470b5c6cebcb4a00ed23b75261916cbe9190a61 Mon Sep 17 00:00:00 2001 From: domi41 Date: Fri, 9 Oct 2020 10:48:28 +0200 Subject: [PATCH 39/40] feat: add grades as a required property upon poll creation --- openapi/components/schemas/poll-new.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/openapi/components/schemas/poll-new.yaml b/openapi/components/schemas/poll-new.yaml index 73ac983..c0e97de 100644 --- a/openapi/components/schemas/poll-new.yaml +++ b/openapi/components/schemas/poll-new.yaml @@ -6,3 +6,4 @@ properties: required: - subject - proposals + - grades From 0eab731bc5732833cd206a6727532c8085cfbc6d Mon Sep 17 00:00:00 2001 From: domi41 Date: Fri, 9 Oct 2020 15:22:13 +0200 Subject: [PATCH 40/40] feat: add levels to grades --- openapi/components/schemas/grade.yaml | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/openapi/components/schemas/grade.yaml b/openapi/components/schemas/grade.yaml index fb28f43..80c0123 100644 --- a/openapi/components/schemas/grade.yaml +++ b/openapi/components/schemas/grade.yaml @@ -3,9 +3,7 @@ properties: id: type: integer description: > - Unique identifier of the grade in its grading. - Zero (0) is the worst grade, and it goes upwards. - TBD - WIP + Identifier of the grade. example: 0 readOnly: true name: @@ -17,5 +15,12 @@ properties: type: string description: An optional description of the grade. example: In this poll, the grade "To reject" disqualifies the proposal. + level: + type: integer + description: | + Unique level of the grade in its grading. + Zero (0) is the worst grade, and it goes upwards. + Each grade of a poll must have a unique level. required: - name + - level