First rough version of openapi.yml

2024-12-27 11:31:05 +01:00
parent ca5fccb809
commit d2df5adef3
1 changed files with 194 additions and 0 deletions
--- a/openapi.yml
+++ b/openapi.yml
@ -0,0 +1,194 @@
+openapi: 3.0.3
+info:
+  title: qv - dlmw
+  description: |-
+    This is the documentation for the qv (Quadratic Voting) API.
+  termsOfService: http://swagger.io/terms/
+  contact:
+    email: dylan@dlmw.ch
+  license:
+    name: GNU General Public License Version 3
+    url: https://www.gnu.org/licenses/gpl-3.0.txt
+  version: 0.0.1
+externalDocs:
+  description: Find out more about qv # todo
+  url: http://swagger.io # todo
+servers:
+  - url: https://petstore3.swagger.io/api/v3 # todo
+tags:
+  - name: election
+    description: Retrieve data related to elections
+
+paths:
+  /election:
+    post:
+      tags:
+        - election
+      summary: Create a new election
+      operationId: createElection
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateElectionRequest"
+      responses:
+        # todo 200:
+        400:
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+
+components:
+  schemas:
+    Election:
+      type: object
+      required:
+        - id
+        - name
+        - tokens
+        - is_anonymous
+        - expires_at
+      properties:
+        id:
+          type: integer
+          format: int64
+          readOnly: true
+        name:
+          type: string
+          minLength: 1
+        tokens:
+          type: integer
+          minimum: 0
+        is_anonymous:
+          type: boolean
+        max_voters:
+          type: integer
+          minimum: 1
+          nullable: true
+          description: Required when election is anonymous
+        created_at:
+          type: string
+          format: date-time
+          readOnly: true
+        expires_at:
+          type: string
+          format: date-time
+        choices:
+          type: array
+          items:
+            $ref: '#/components/schemas/Choice'
+        voters:
+          type: array
+          items:
+            $ref: '#/components/schemas/Voter'
+
+    Choice:
+      type: object
+      required:
+        - text
+        - election_id
+      properties:
+        text:
+          type: string
+          minLength: 1
+        election_id:
+          type: integer
+          format: int64
+
+    Voter:
+      type: object
+      required:
+        - identity
+        - election_id
+      properties:
+        identity:
+          type: string
+          minLength: 1
+          description: When election is anonymous, passcodes will be pre-generated
+        election_id:
+          type: integer
+          format: int64
+        votes:
+          type: array
+          items:
+            $ref: '#/components/schemas/Vote'
+
+    Vote:
+      type: object
+      required:
+        - voter_identity
+        - election_id
+      properties:
+        voter_identity:
+          type: string
+          minLength: 1
+        election_id:
+          type: integer
+          format: int64
+        choice_text:
+          type: string
+          nullable: true
+        tokens:
+          type: integer
+          minimum: 0
+          nullable: true
+        calculated_vote_count:
+          type: integer
+          readOnly: true
+          description: Calculated as floor(sqrt(tokens))
+        created_at:
+          type: string
+          format: date-time
+          readOnly: true
+
+    CreateElectionRequest:
+      type: object
+      required:
+        - name
+        - tokens
+        - is_anonymous
+        - expires_at
+        - choices
+      properties:
+        name:
+          type: string
+          minLength: 1
+        tokens:
+          type: integer
+          minimum: 0
+        is_anonymous:
+          type: boolean
+        max_voters:
+          type: integer
+          minimum: 1
+          nullable: true
+          description: Required when election is anonymous
+        expires_at:
+          type: string
+          format: date-time
+        choices:
+          type: array
+          items:
+            type: string
+            minLength: 1
+          minItems: 1
+          uniqueItems: true
+
+    ErrorResponse:
+      type: object
+      required:
+        - message
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        code:
+          type: string
+          description: Machine-readable error code
+        details:
+          type: object
+          description: Additional error details when available
+          nullable: true