Verified Commit fcfebca4 authored by Jakob Moser's avatar Jakob Moser
Browse files

Start adding API (+ documentation)

parent e353614f

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

+49 −0
Changes for portal/static/docs/api/v0/openapi-spec.yaml: 49 added lines, 0 removed lines.
Original line number Diff line number Diff line
@@ -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