From 985ad1dbed63c28a57b55741bc3933ec3b82c66c Mon Sep 17 00:00:00 2001 From: Frank Elsinga Date: Sun, 23 Jun 2024 22:39:21 +0200 Subject: [PATCH] documented the api changes --- openapi.yaml | 311 ++++++++++++++++------------ server/main-api/src/calendar/mod.rs | 8 +- webclient/api_types/index.ts | 61 ++++-- 3 files changed, 221 insertions(+), 159 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 8dab29698..5f095de73 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7,11 +7,16 @@ info: NavigaTUM is a tool developed by students for students, to help you get around at [TUM](https://tum.de). Feel free to contribute. - Features: - - - Interactive or static maps to lookup the position of rooms or buildings - - Fast and typo-tolerant search - - Support for different room code formats as well as generic names + - [x] 🗺️ Interactive/static maps to look up the position of rooms or buildings + - [x] 🔍 Fast and typo-tolerant search + - [x] 💾 Support for different room code formats as well as generic names + - [x] 🤖 All functionality is also available via an open and well documented API + - [x] 🗘 Automatically update the data from upstream datasources + - [ ] 🗨️ Allow students/staff to easily submit feedback and data patches + - [ ] 🏫 Generate maps from CAD data sources + - [ ] 🚶🏻 Generate turn by turn navigation advice for navigating end to end + + If you'd like to help out or join us in this adventure, we would love to talk to you. All functionality is also available via an API. @@ -61,22 +66,22 @@ paths: schema: type: string examples: - '5304': - summary: A 'misspelled' (according to tumonline) lecture-hall + mi hs1: + summary: \'misspelled\' (according to tumonline) lecture-hall value: mi hs1 - garching: - summary: A misspelled campus + sfarching: + summary: misspelled campus garching value: sfarching - fsmpi: - summary: A regular room + 5606.EG.036: + summary: regular room (fsmpic) value: 5606.EG.036 interims: - summary: Lecture halls + summary: \'interims\' Lecture halls value: interims - sv: - summary: common name + AStA: + summary: common name synonyms for SV value: AStA - none: + all: summary: All rooms value: '' - name: limit_buildings @@ -124,7 +129,7 @@ paths: summary: 'The default value (See [Wikipedia](https://en.wikipedia.org/wiki/C0_and_C1_control_codes#Modified_C0_control_code_sets)).' value: /u0019 em: - summary: A good alternative default value + summary: good alternative default value value: ais-highlight: summary: Another good alternative @@ -144,7 +149,7 @@ paths: summary: 'The default value (See [Wikipedia](https://en.wikipedia.org/wiki/C0_and_C1_control_codes#Modified_C0_control_code_sets)).' value: /u0017 em: - summary: A good alternative default value + summary: good alternative default value value: ais-highlight: summary: Another good alternative @@ -304,32 +309,32 @@ paths: type: string examples: '5304': - summary: A normal building + summary: normal building value: '5304' garching: - summary: The garching campus + summary: garching campus value: garching mri: - summary: The MRI campus - value: garching + summary: MRI campus + value: mri mi: - summary: 'A large, (custom named) building' + summary: large building (mi) value: mi mw: - summary: 'An other large, (custom named) building' + summary: other large building (mw) value: mw - fsmpi: - summary: A regular room + 5606.EG.036: + summary: regular room (fsmpic) value: 5606.EG.036 - rechnerhalle: - summary: A room with custom props added + 5605.EG.011: + summary: room with custom props (rechnerhalle-mi) value: 5605.EG.011 - tb-chemie: - summary: A virtual room + 5401.01.100A: + summary: virtual room (tb-chemie) value: 5401.01.100A - humangenetik: - summary: A virtual room - value: Gebäude 1543 + '1543': + summary: virtual room (humangenetik) + value: '1543' responses: '200': description: More data about the requested building/room @@ -721,82 +726,52 @@ paths: - Not found tags: - core - '/api/calendar/{id}': + '/api/calendar': get: operationId: calendar summary: Retrieve Calendar Entries description: | - Retrieves calendar entries for a specific `id` within the requested time span. + Retrieves calendar entries for specific `ids` within the requested time span. The time span is defined by the `start_after` and `end_before` query parameters. Ensure to provide valid date-time formats for these parameters. If successful, returns additional entries in the requested time span. - parameters: - - name: start_after - in: query - description: The first allowed time the calendar would like to display - required: true - schema: - type: string - format: date-time - examples: - use_tz: - summary: how timezones are defined - value: '2039-01-19T03:14:07+01:00' - utc: - summary: how utc is defined - value: '2042-01-07T00:00:00 UTC' - - name: end_before - in: query - description: The last allowed time the calendar would like to display - required: true - schema: - type: string - format: date-time - examples: - use_tz: - summary: how timezones are defined - value: '2039-01-19T03:14:07+01:00' - utc: - summary: how utc is defined - value: '2042-01-07T00:00:00 UTC' - - name: id - in: path - description: string you want to search for - required: true - schema: - type: string - examples: - '5304': - summary: A normal building - value: '5304' - root: - summary: The root entry of the NavigaTUM-data - value: root - garching: - summary: The garching campus - value: garching - mri: - summary: The MRI campus - value: garching - mi: - summary: 'A large, (custom named) building' - value: mi - mw: - summary: 'An other large, (custom named) building' - value: mw - fsmpi: - summary: A regular room - value: 5606.EG.036 - rechnerhalle: - summary: A room with custom props added - value: 5605.EG.011 - tb-chemie: - summary: A virtual room - value: 5401.01.100A - humangenetik: - summary: A virtual room - value: '1543' + requestBody: + description: + required: true + content: + application/json: + schema: + type: object + properties: + start_after: + description: The first allowed time the calendar would like to display + type: string + format: date-time + examples: + - '2039-01-19T03:14:07+01:00' + - '2042-01-07T00:00:00 UTC' + end_before: + description: The last allowed time the calendar would like to display + type: string + format: date-time + examples: + - '2039-01-19T03:14:07+01:00' + - '2042-01-07T00:00:00 UTC' + ids: + description: ids you want the calendars for + type: array + items: + type: string + examples: + - 5605.EG.011 + - 5510.02.001 + - 5606.EG.036 + - '5304' + required: + - ids + - end_before + - start_after responses: '200': description: More entries of the calendar in the requested time span @@ -853,31 +828,31 @@ paths: type: string examples: '5304': - summary: A normal building + summary: normal building value: '5304' garching: - summary: The garching campus + summary: garching campus value: garching mri: - summary: The MRI campus - value: garching + summary: MRI campus + value: mri mi: - summary: 'A large, (custom named) building' + summary: large building (mi) value: mi mw: - summary: 'An other large, (custom named) building' + summary: other large building (mw) value: mw - fsmpi: - summary: A regular room + 5606.EG.036: + summary: regular room (fsmpic) value: 5606.EG.036 - rechnerhalle: - summary: A room with custom props added + 5605.EG.011: + summary: room with custom props (rechnerhalle-mi) value: 5605.EG.011 - tb-chemie: - summary: A virtual room + 5401.01.100A: + summary: virtual room (tb-chemie) value: 5401.01.100A - humangenetik: - summary: A virtual room + '1543': + summary: virtual room (humangenetik) value: '1543' responses: '200': @@ -1104,17 +1079,32 @@ paths: type: string examples: '5304': - summary: A normal building + summary: normal building value: '5304' garching: - summary: A campus + summary: garching campus value: garching + mri: + summary: MRI campus + value: mri mi: - summary: 'A large, (custom named) building' + summary: large building (mi) value: mi - fsmpi: - summary: A regular room + mw: + summary: other large building (mw) + value: mw + 5606.EG.036: + summary: regular room (fsmpic) value: 5606.EG.036 + 5605.EG.011: + summary: room with custom props (rechnerhalle-mi) + value: 5605.EG.011 + 5401.01.100A: + summary: virtual room (tb-chemie) + value: 5401.01.100A + '1543': + summary: virtual room (humangenetik) + value: '1543' - name: counter in: path description: counter of the image you want. @@ -1846,9 +1836,19 @@ components: - site - campus - poi + examples: + - room + - building + - joined_building + - area + - site + - campus + - poi type_common_name: description: The type of the entry in a human-readable form type: string + examples: + - "Serverraum" name: description: The name of the entry in a human-readable form type: string @@ -2042,30 +2042,73 @@ components: required: - id - name - CalendarResponse: + CalendarLocation: type: object properties: - events: - description: The entries of the requested - type: array - items: - $ref: '#/components/schemas/CalendarEntry' - last_sync: - description: When the last sync with TUMonline happened. + name: + description: The name of the entry in a human-readable form type: string - format: date-time examples: - - '2018-01-01T00:00:00' + - '5602.EG.001 (MI HS 1, Friedrich L. Bauer Hörsaal)' + - '5121.EG.003 (Computerraum)' + last_calendar_scrape_at: + description: the last time the calendar was scraped for this room + type: string + examples: + - '2039-01-19T03:14:07+01:00' + - '2042-01-07T00:00:00 UTC' calendar_url: - description: 'Link to the same calendar, but in TUMonline' + description: A link to the calendar of the room type: string examples: - - 'https://campus.tum.de/tumonline/wbKalender.wbRessource?pResNr=12543' - pattern: 'https:\/\/campus\.tum\.de\/tumonline\/wbKalender\.wbRessource\?pResNr=[0-9]+' + - 'https://campus.tum.de/tumonline/tvKalender.wSicht?cOrg=19691&cRes=12543&cReadonly=J' + - 'https://campus.tum.de/tumonline/tvKalender.wSicht?cOrg=19691&cRes=12559&cReadonly=J' + type_common_name: + description: The type of the entry in a human-readable form + type: string + examples: + - "Serverraum" + type: + description: The type of the entry + type: string + enum: + - room + - building + - joined_building + - area + - site + - campus + - poi + examples: + - room + - building + - joined_building + - area + - site + - campus + - poi required: - - events - - last_sync + - name + - last_calendar_scrape_at - calendar_url + - type_common_name + - type + CalendarResponse: + type: object + description: room-code to calendar entry's record + additionalProperties: + type: object + properties: + events: + description: The entries of the requested + type: array + items: + $ref: '#/components/schemas/CalendarEntry' + location: + $ref: '#/components/schemas/CalendarLocation' + required: + - events + - location CalendarEntry: type: object properties: diff --git a/server/main-api/src/calendar/mod.rs b/server/main-api/src/calendar/mod.rs index 3755e5f32..491777e5f 100644 --- a/server/main-api/src/calendar/mod.rs +++ b/server/main-api/src/calendar/mod.rs @@ -1,6 +1,6 @@ use std::collections::HashMap; -use actix_web::{get, web, HttpResponse}; +use actix_web::{get, HttpResponse, web}; use chrono::{DateTime, Utc}; use log::error; use serde::{Deserialize, Serialize}; @@ -129,15 +129,15 @@ async fn get_from_db( #[cfg(test)] mod tests { + use actix_web::App; use actix_web::http::header::ContentType; use actix_web::test; - use actix_web::App; use lazy_static::lazy_static; use pretty_assertions::assert_eq; use serde_json::Value; - use crate::setup::tests::PostgresTestContainer; use crate::AppData; + use crate::setup::tests::PostgresTestContainer; use super::*; @@ -252,7 +252,7 @@ mod tests { let (locations, events) = sample_data(); for (key, data) in locations { for lang in ["de", "en"] { - let query =format!("INSERT INTO {lang}(key,data,last_calendar_scrape_at) VALUES ('{key}','{data}','{now_rfc3339}')"); + let query = format!("INSERT INTO {lang}(key,data,last_calendar_scrape_at) VALUES ('{key}','{data}','{now_rfc3339}')"); sqlx::query(&query).execute(&mut *tx).await.unwrap(); } } diff --git a/webclient/api_types/index.ts b/webclient/api_types/index.ts index 691510774..f196c03fc 100644 --- a/webclient/api_types/index.ts +++ b/webclient/api_types/index.ts @@ -29,10 +29,10 @@ export type paths = { */ get: operations["details"]; }; - "/api/calendar/{id}": { + "/api/calendar": { /** * Retrieve Calendar Entries - * @description Retrieves calendar entries for a specific `id` within the requested time span. + * @description Retrieves calendar entries for specific `ids` within the requested time span. * The time span is defined by the `start_after` and `end_before` query parameters. * Ensure to provide valid date-time formats for these parameters. * @@ -502,16 +502,28 @@ export type components = { /** @description Human display name */ readonly name: string; }; - readonly CalendarResponse: { - /** @description The entries of the requested */ - readonly events: readonly components["schemas"]["CalendarEntry"][]; + readonly CalendarLocation: { + /** @description The name of the entry in a human-readable form */ + readonly name: string; + /** @description the last time the calendar was scraped for this room */ + readonly last_calendar_scrape_at: string; + /** @description A link to the calendar of the room */ + readonly calendar_url: string; + /** @description The type of the entry in a human-readable form */ + readonly type_common_name: string; /** - * Format: date-time - * @description When the last sync with TUMonline happened. + * @description The type of the entry + * @enum {string} */ - readonly last_sync: string; - /** @description Link to the same calendar, but in TUMonline */ - readonly calendar_url: string; + readonly type: "room" | "building" | "joined_building" | "area" | "site" | "campus" | "poi"; + }; + /** @description room-code to calendar entry's record */ + readonly CalendarResponse: { + [key: string]: { + /** @description The entries of the requested */ + readonly events: readonly components["schemas"]["CalendarEntry"][]; + readonly location: components["schemas"]["CalendarLocation"]; + }; }; readonly CalendarEntry: { /** @@ -793,23 +805,30 @@ export type operations = { }; /** * Retrieve Calendar Entries - * @description Retrieves calendar entries for a specific `id` within the requested time span. + * @description Retrieves calendar entries for specific `ids` within the requested time span. * The time span is defined by the `start_after` and `end_before` query parameters. * Ensure to provide valid date-time formats for these parameters. * * If successful, returns additional entries in the requested time span. */ calendar: { - parameters: { - query: { - /** @description The first allowed time the calendar would like to display */ - start_after: string; - /** @description The last allowed time the calendar would like to display */ - end_before: string; - }; - path: { - /** @description string you want to search for */ - id: string; + /** @description null */ + readonly requestBody: { + readonly content: { + readonly "application/json": { + /** + * Format: date-time + * @description The first allowed time the calendar would like to display + */ + readonly start_after: string; + /** + * Format: date-time + * @description The last allowed time the calendar would like to display + */ + readonly end_before: string; + /** @description ids you want the calendars for */ + readonly ids: readonly string[]; + }; }; }; responses: {