Problem
Die aktuelle serverseitige OpenAPI-Implementierung erlaubt es nicht, einen Endpunkt zu definieren, der Binärdaten zurückgibt. Jedes Ergebnis einer Operation wird entweder in JSON serialisiert oder in einen String umgewandelt, bevor es in die HTTP-Antwort geschrieben wird – es gibt keine Möglichkeit, Rohdaten (z. B. application/octet-stream, image/*, application/pdf) an den Aufrufer zu streamen.
Grundursache
In com.top_logic.service.openapi.server.impl.ServiceMethodByExpression#handleRequest wird der Antworttext immer über den Zeichen-Writer geschrieben:
{{{#!java resp.getWriter().write(content); // content ist immer ein String }}}
Der Wert von ` content ` wird auf genau zwei Arten gebildet:
- Standard (kein Response -Wrapper): content = JSON.toString(result) – jeder Rückgabewert wird JSON-serialisiert.
- Mit Response-Wrapper (HTTPResponse-TL-Script-Funktion ): Wenn der MIME-Typ „application/json“ ist, dann content = JSON.toString(response.getResult()); andernfalls content = String.valueOf(response.getResult()).
HttpServletResponse#getOutputStream() wird niemals für Antworten von Benutzer-Endpunkten verwendet. Es gibt keine Sonderbehandlung für Rückgabewerte vom Typ „BinaryData“, „byte[]“ oder „InputStream“ – diese fallen unter den „else“- Zweig und werden entweder JSON-serialisiert oder über „String.valueOf(...)“ umgewandelt, wodurch der binäre Inhalt zerstört wird.
Die Javadoc von com.top_logic.service.openapi.server.impl.Response dokumentiert diese Einschränkung bereits:
> „in HttpServletResponse#getWriter() geschrieben“ – d. h., ausschließlich Zeichenausgabe.
Schema- vs. Laufzeit-Diskrepanz
com.top_logic.service.openapi.server.parameter.ParameterFormat definiert einen Eintrag „BINARY“, der von OperationResponse#getFormat() wiederverwendet wird. „BINARY“ wird im generierten OpenAPI-Spezifikationsdokument als Schema-Annotation ausgegeben, es gibt jedoch keine entsprechende Laufzeitbehandlung im Response-Writer. Der veröffentlichte Vertrag gibt daher falsche Angaben darüber, was der Endpunkt tatsächlich liefern kann.
Asymmetrie gegenüber der Client-Seite
Die Client-Seite (die eine Remote-API nutzt) unterstützt binäre Antworten: com.top_logic.service.openapi.client.registry.impl.response.ResponseHandlerByExpression ruft für das BINARY- Format EntityUtils.toByteArray(entity) auf und gibt ein byte[] an TL-Script zurück. Nur die Serverseite (die eine Antwort generiert) funktioniert nicht.
Vorgeschlagene Korrektur
In ` ServiceMethodByExpression#handleRequest` nach dem Ergebnistyp verzweigen:
- Wenn das Ergebnis ein ` BinaryData`, ein `byte[]` oder ein `InputStream` ist (oder wenn das deklarierte/als Antwort zurückgegebene `ParameterFormat` „BINARY“ ist), schreibe die Rohbytes über `resp.getOutputStream()` statt über `resp.getWriter()`.
- Behalten Sie in allen anderen Fällen den aktuellen JSON-/String-Pfad bei.
Zusätzlich sollte „Response“ (der HTTPResponse-TL-Script-Wrapper ) binäre Nutzdaten akzeptieren, damit ein Skript explizit „application/octet-stream“, „application/pdf“, „image/*“ usw. mit korrekt gesetztem „Content-Type“ und „Content-Length“ zurückgeben kann.
Betroffene Dateien
- com.top_logic.service.openapi.server/src/main/java/com/top_logic/service/openapi/server/impl/ServiceMethodByExpression.java (Zeilen 79–112)
- com.top_logic.service.openapi.server/src/main/java/com/top_logic/service/openapi/server/impl/Response.java (Javadoc + möglicherweise neues Feld für binäre Nutzdaten)
- com.top_logic.service.openapi.server/src/main/java/com/top_logic/service/openapi/server/parameter/ParameterFormat.java (Laufzeit-Hook für „BINARY“ auf der Antwortseite)
Migration
Die Antwortverarbeitung in `ServiceMethodByExpression ` hat sich geändert. Bisher wurden alle Endpunkt-Ergebnisse bedingungslos als JSON (application/json) serialisiert. Nun wird der Inhaltstyp durch den Ergebnistyp bestimmt:
| Ergebnistyp | Vorher | Nach |
| Map, Collection | application/json | application/json (unverändert) |
| BinaryData, byte[], InputStream | application/json (fehlerhaft) | Binärstrom mit korrektem Inhaltstyp |
| String, andere Primitive | application/json (JSON-Zeichenkette in Anführungszeichen) | text/plain (unformatierte Zeichenfolge, keine JSON-Anführungszeichen) |
Wer ist betroffen?
Endpunkte, deren TL-Script-Ausdruck eine Zeichenkette (oder einen anderen Wert, der weder eine Map, noch eine Collection noch ein binärer Wert ist) zurückgibt und deren Clients so konfiguriert sind, dass sie die Antwort als JSON parsen.
Endpunkte, die Map- oder Collection-Werte zurückgeben, sind nicht betroffen – sie werden weiterhin als „application/json“ serialisiert.
Endpunkte, die `response(statusCode, content)` ohne das Argument `contentType` verwenden, sind ebenfalls betroffen: Der bisherige Standardwert `application/json` entfällt; der Inhaltstyp wird nun wie in der obigen Tabelle beschrieben aus dem `content`-Parameter abgeleitet. Übergeben Sie explizit „application/json“, um das bisherige Verhalten beizubehalten.
So führen Sie die Migration durch
Option 1: Ändern Sie das Antwortformat des Clients auf TEXT
Navigieren Sie in der OpenAPI-Client-Konfiguration (Service-Editor > TL-Script-Funktionen für externe APIs) zu:
Funktionsdefinitionen > name > Antwortbearbeitung > Format
Wechseln Sie von JSON zu Text. Der Client erhält dann die Rohzeichenfolge direkt, ohne dass eine JSON-Auswertung erfolgt.
Option 2: Strukturierte Daten anstelle einer Zeichenkette zurückgeben
Ändern Sie den serverseitigen TL-Script-Ausdruck so, dass er eine Map oder eine Liste anstelle einer verketteten Zeichenkette zurückgibt. Ersetzen Sie beispielsweise:
.sort()
.reduce("", subresult -> element -> $subresult == "" ? $element : ($subresult + ", " + $element))
durch:
.sort()
Die sortierte Liste (eine Collection) wird automatisch als JSON-Array (["A1", "A3"]) serialisiert. Passen Sie die Client-Assertion entsprechend an.
Option 3: Setzen Sie „application/json“ explizit in der Serverantwort
Verwenden Sie die TL-Script-Funktion `response()`, um den JSON-Inhaltstyp zu erzwingen:
response(200, $result, "application/json")
Dadurch verhält sich der Endpunkt genau wie zuvor.
Erkennung
grep -rln -e 'OpenApiServer' -e 'response(' --include=*.xml .