chore: Add some documentation

src/openapi.yaml

@@ -4,8 +4,60 @@ info:
   version: 1.0.0
   contact:
     email: sean@black-burn.ch
-  description: >
+  description: |
     OpenAPI documentation of the modulplaner API
+
+
+    ## Optional endpoints
+
+    This OpenAPI spec contains some "optional" endpoints. This is down to the fact, that
+    the module planner can be used on a static website, or also be integrated into a
+    server that is connected to a database.
+
+    When the Modulplaner is set to be hosted on a static site, the endpoints marked with
+    `[OPTIONAL:*]` can not be reached.
+
+    - `[OPTIONAL:Storage]`: Storage endpoints for the users/students
+    - `[OPTIONAL:Management]`: management endpoints for administrators
+
+    ### Static site
+    If the modulplaner is hosted on a static site, only the `GET` endpoints are
+    required, the `/me` endpoints also are not required in that case.
+
+    The endpoints can be implemented by hosting the files statically in a directory
+    structure.
+
+
+    ## Authentication
+
+    The defined authentication can be exchanged for any valid authentication. The spec
+    only represents which endpoints should require authentication when implementing a
+    server.
+
+
+    ## Types used
+
+    The numeric fields have an additional `format` tag assigned.
+
+
+    ### Unsigned
+
+    - `u…`: Unsigned … bit
+    - `u8`: Unsigned 8 bit (0 - 255)
+    - `u16`: Unsigned 16 bit (0 - 65'535)
+
+
+    ### Signed
+
+    - `i…`: Signed … bit
+    - `i8`: Signed 8 bit (-128 - 127)
+    - `i16`: Signed 16 bit (-32'768 - 32'767)
+
+
+    ### Floating
+
+    - `f32`: 32 bit floating point number
+    - `f64`: 64 bit floating point number
   license:
     name: MPL 2.0
     url: https://www.mozilla.org/en-US/MPL/2.0/