From 701886428483176a7bcfb3f3fbda706eae6e0687 Mon Sep 17 00:00:00 2001
From: Michael Kutzner <174690291+MichaelKutzner@users.noreply.github.com>
Date: Tue, 19 Nov 2024 15:24:42 +0100
Subject: [PATCH] Add documentation for footpath duration

---
 openapi.yaml | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/openapi.yaml b/openapi.yaml
index 178deb819..ab8038ca6 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -1303,7 +1303,19 @@ components:
         to:
           $ref: '#/components/schemas/Place'
         duration:
-          description: Leg duration in seconds
+          description: |
+            Leg duration in seconds
+
+            If leg is footpath:
+              The footpath duration is derived from the default footpath
+              duration using the query parameters `transferTimeFactor` and
+              `additionalTransferTime` as follows:
+              `leg.duration = defaultDuration * transferTimeFactor + additionalTransferTime.`
+              In case the defaultDuration is needed, it can be calculated by
+              `defaultDuration = (leg.duration - additionalTransferTime) / transferTimeFactor`.
+              Note that the default values are `transferTimeFactor = 1` and
+              `additionalTransferTime = 0` in case they are not explicitly
+              provided in the query.
           type: integer
         startTime:
           type: string