Start adding API (+ documentation)

portal/static/docs/api/v0/openapi-spec.yaml

@@ -13,6 +13,37 @@ servers:
     - url: http://localhost:5000/api/v0
       description: Development server on localhost
 paths:
+    /agendas/-/items:
+        summary: Path used to manage the items of _the_ agenda.
+        description: ""
+        get:
+            responses:
+                "200":
+                    content:
+                        application/json:
+                            schema:
+                                type: array
+                                items:
+                                    $ref: "#/components/schemas/AgendaItem"
+                    description: Successful response, returns a list of items
+            operationId: getTheAgendaItems
+            summary: List all items on the agenda
+            description: |
+                This returns all items currently on the agenda for a Fachschaftssitzung. The items are directly sourced from the todo tool _Taiga_ ([fsco.li/todo](https://fsco.li/todo)).
+
+                ### Which Fachschaftssitzung?
+
+                This API does not know. It only takes whatever is currently in the column “Nächste Fachschaftssitzung” in Taiga and returns this. Depending on when the next Fachschaftssitzung is, this can mean that this path returns the items on the agenda ...
+
+                * ... of the upcoming Fachschaftssitzung
+                * ... of the current Fachschaftssitzung (if accessed during one)
+                * ... of the previous Fachschaftssitzung (if accessed immediately after one)
+
+                ### What's up with the weird path?
+
+                `/agendas/-/items` seems needlessly complicated, but there is a reason for that:
+
+                <!-- TODO -->
     /version:
         summary: Path used to get details about the version of this application.
         description: ""
@@ -84,6 +115,24 @@ paths:
               required: true
 components:
     schemas:
+        AgendaItem:
+            title: Item on an agenda
+            description: "An item on an agenda. It has a name and an id."
+            required:
+                - id
+                - name
+            type: object
+            properties:
+                id:
+                    description: Id of the item, as provided by the Taiga todo tool.
+                    type: integer
+                    readOnly: true
+                name:
+                    description: Human-readable name of the item.
+                    type: string
+            example:
+                id: 349
+                name: "Sommer-Coliwochendende: Veranstalten"
         ApplicationVersion:
             title: ApplicationVersion
             description: Version details about the application