enhancement
major
defect
major
minor
minor
#29754
OpenAPI-Server: Variablenname für Request-Parameter, deren Name kein gültiger TL-Script-Bezeichner ist (z.B. Header X-Gitea-Event)
Der Name eines Request-Parameters einer OpenAPI-Server-Operation ist gleichzeitig der Name der TL-Script-Variablen, unter der die Implementierung den Wert erhält. Die Konfiguration erlaubt dafür Bindestriche (RequestParameter.Config.VARIABLE_NAME_PATTERN = "[\\w\\-]+", com.top_logic.service.openapi.server.parameter.RequestParameter), die TL-Script-Grammatik jedoch nicht (SearchExpressionParser.jj, Token NAME : ["A"-"Z","a"-"z","_"] (["A"-"Z","a"-"z","_","0"-"9"])*).
Folge: Ein Header-Parameter wie X-Gitea-Event (oder X-GitHub-Event, X-Request-Id, …) lässt sich zwar konfigurieren, kann in der Implementierung aber nie referenziert werden ($X-Gitea-Event ist $X - Gitea - Event). Webhook-Empfänger müssen das Ereignis deshalb aus der Struktur des Payloads raten.
Betroffen: z.B. der Webhook-Empfänger der Release-Notes-Anwendung (POST /api/v2/gitea), der das Gitea-Ereignis deshalb am Payload erkennt.
Lösung
- Request-Parameter (und Teile eines Multipart-Bodys) erhalten die optionale Eigenschaft Variablenname (variable-name). Der Parametername bleibt der Name in der API (Header, Query, Cookie, Pfad, Formularfeld), der Variablenname ist der Name, unter dem die TL-Script-Implementierung den Wert erhält.
- Ist kein Variablenname angegeben, ist der Parametername der Variablenname (unverändertes Verhalten für alle bisher nutzbaren Parameter).
- Ist der Parametername kein gültiger TL-Script-Bezeichner (z.B. X-Gitea-Event), ist der Variablenname Pflicht; der Konfigurationseditor zeigt den Fehler direkt am Feld. Ein angegebener Variablenname muss selbst ein gültiger Bezeichner sein. Zwei Parameter einer Operation dürfen nicht denselben Variablennamen haben.
- Export der API-Beschreibung: ein gesetzter Variablenname wird als Erweiterung x-tl-variable-name am Parameter (bzw. im Schema des Multipart-Teils) ausgegeben und beim Import wieder gelesen, so dass Export/Import die Implementierung nicht bricht.
- Import einer fremden API-Beschreibung ohne x-tl-variable-name: für Parameter mit ungültigem Namen wird ein Variablenname vorbelegt (ungültige Zeichen durch _` ersetzt, z.B. `X-Gitea-Event → X_Gitea_Event).
Migration
OpenAPI-Server-Konfigurationen, die Request-Parameter (oder Multipart-Body-Teile) mit einem Namen enthalten, der kein gültiger TL-Script-Bezeichner ist (z.B. mit -), lassen sich ohne Variablenname nicht mehr laden. Für solche Parameter in der Service-Konfiguration des OpenAPI-Servers einen Variablennamen setzen, z.B. {{{#!xml <parameter class="com.top_logic.service.openapi.server.parameter.HeaderParameter" name="X-Gitea-Event" variable-name="event" .../> }}} In der Implementierung ist der Wert dann als $event verfügbar (vorher war er dort nicht erreichbar).