backend: add documentation

Author: schmolldechse

backend/controllers/StationsController.ts

@@ -1,9 +1,10 @@
 import { type Station } from "../models/station.ts";
 import { mapToEnum, Products } from "../models/products.ts";
-import { Controller, Get, Path, Query, Res, Route, type TsoaResponse } from "tsoa";
+import { Controller, Get, Path, Query, Res, Route, Tags, type TsoaResponse } from "tsoa";
 import { getRedisClient } from "../lib/redis.ts";
 
 @Route("stations")
+@Tags("Stations")
 export class StationController extends Controller {
 	@Get()
 	async queryStations(

backend/controllers/timetable/BahnhofController.ts

@@ -1,5 +1,5 @@
 import { type RequestType, retrieveBahnhofJourneys } from "./requests.ts";
-import { Controller, Get, Queries, Route } from "tsoa";
+import { Controller, Get, Queries, Route, Tags } from "tsoa";
 import type { Journey } from "../../models/connection.ts";
 
 class BahnhofQuery {
@@ -10,6 +10,7 @@ class BahnhofQuery {
 }
 
 @Route("timetable/bahnhof")
+@Tags("Bahnhof")
 export class BahnhofController extends Controller {
 	@Get()
 	async getBahnhofJourneys(@Queries() query: BahnhofQuery): Promise<Journey[]> {

backend/controllers/timetable/CombinedController.ts

@@ -3,7 +3,7 @@ import { RequestType, retrieveBahnhofJourneys, retrieveCombinedConnections } fro
 import type { Connection, Journey } from "../../models/connection.ts";
 import { isMatching } from "../../lib/merge.ts";
 import calculateDuration from "../../lib/time.ts";
-import { Controller, Get, Queries, Res, Route, type TsoaResponse } from "tsoa";
+import { Controller, Get, Queries, Res, Route, Tags, type TsoaResponse } from "tsoa";
 
 class CombinedQuery {
 	evaNumber!: string;
@@ -15,6 +15,7 @@ class CombinedQuery {
 }
 
 @Route("timetable/combined")
+@Tags("Combined")
 export class CombinedController extends Controller {
 	@Get()
 	async getCombinedJourneys(

backend/controllers/timetable/VendoController.ts

@@ -1,6 +1,6 @@
 import { DateTime } from "luxon";
 import { Profile, RequestType, retrieveCombinedConnections, retrieveConnections } from "./requests.ts";
-import { Controller, Get, Queries, Res, Route, type TsoaResponse } from "tsoa";
+import { Controller, Get, Queries, Res, Route, Tags, type TsoaResponse } from "tsoa";
 import type { Journey } from "../../models/connection.ts";
 
 class VendoQuery {
@@ -13,6 +13,7 @@ class VendoQuery {
 }
 
 @Route("timetable/vendo")
+@Tags("Vendo")
 export class VendoController extends Controller {
 	@Get()
 	async getVendoJourneys(

backend/tsoa.json

@@ -6,7 +6,29 @@
 		"outputDirectory": "build",
 		"specVersion": 3,
 		"version": "1.0.0",
-		"basePath": "/api/v1/"
+		"basePath": "/api/v1/",
+		"tags": [
+			{
+				"name": "Bahnhof",
+				"description": "Returns journeys from the DeutscheBahn Bahnhof API. All journeys are returned with a RIS ID"
+			},
+			{
+				"name": "Vendo",
+				"description": "Returns journeys from the [email protected]. It is possible to select the profile which returns the journeys with the depending ID of the profile",
+				"externalDocs": {
+					"description": "See more in the API Documentation",
+					"url": "https://github.com/public-transport/db-vendo-client"
+				}
+			},
+			{
+				"name": "Combined",
+				"description": "Combines both Bahnhof & Vendo journeys into a single response for better convenience"
+			},
+			{
+				"name": "Stations",
+				"description": "Returns all stations from the DeutscheBahn API"
+			}
+		]
 	},
 	"routes": {
 		"routesDir": "build",