add initial openapi spec

booklet.py

@@ -130,3 +130,9 @@ def generate_errors(errors: dict[str, tuple[list[str], list[str]]], name: str):
     Generates the error page using the template at templates/errors.html
     """
     return env.get_template("errors.html").render(errors=errors, name=name)
+
+def generate_schema():
+    """
+    Generates the schema page using the template at templates/openapi.yaml.
+    """
+    return env.get_template("openapi.yaml").render()

process.py

@@ -224,6 +224,8 @@ def process_csv(filename: str):
         orientation_events if config["orientation"]["include_in_booklet"] else []
     )
 
+    schema = booklet.generate_schema()
+
     errors = get_invalid_events(orientation_events, api_response)
 
     print("Processing complete!")
@@ -245,6 +247,8 @@ def process_csv(filename: str):
     shutil.copytree("static", "output/static")
     with open("output/api.json", "w", encoding="utf-8") as w:
         json.dump(api_response, w)
+    with open("output/openapi.yaml", "w", encoding="utf-8") as s:
+        s.write(schema)
     with open("output/booklet.html", "w", encoding="utf-8") as b:
         b.write(booklet_html)
     with open("output/index.html", "w", encoding="utf-8") as i:

templates/openapi.yaml

@@ -0,0 +1,107 @@
+openapi: 3.0.0
+
+info:
+  title: T-REX, the DormCon REX API
+  description: Backend for REX events
+  version: 1.0.0
+
+servers:
+  - url: https://rex.mit.edu
+
+paths:
+  /api.json:
+    get:
+      summary: Returns all REX Event data.
+      responses:
+        "200":
+          description: A JSON object containing all REX Event data.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  name:
+                    type: string
+                  published:
+                    type: string
+                    format: "date-time"
+                  events:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/Event"
+                  dorms:
+                    type: array
+                    items:
+                      type: string
+                  tags:
+                    type: array
+                    items:
+                      type: string
+                  colors:
+                    $ref: "#/components/schemas/ColorConfig"
+                required:
+                  - name
+                  - published
+                  - events
+                  - dorms
+                  - tags
+                  - colors
+
+components:
+  schemas:
+    Event:
+      type: object
+      properties:
+        name:
+          type: string
+        dorm:
+          type: array
+          items:
+            type: string
+        location:
+          type: string
+        start:
+          type: string
+          format: "date-time"
+        end:
+          type: string
+          format: "date-time"
+        description:
+          type: string
+        tags:
+          type: array
+          items:
+            type: string
+        group:
+          type: string
+          nullable: true
+        emoji:
+          type: array
+          items:
+            type: string
+      required:
+        - name
+        - dorm
+        - location
+        - start
+        - end
+        - description
+        - tags
+        - group
+
+    ColorConfig:
+      type: object
+      properties:
+        dorms:
+          type: object
+          additionalProperties:
+            type: string
+            pattern: "^#[0-9a-fA-F]{6}$"
+        tags:
+          type: object
+          additionalProperties:
+            type: string
+            pattern: "^#[0-9a-fA-F]{6}$"
+      required:
+        - dorms
+        - tags