[csharp] Serialize header parameters with content: application/json as JSON

Merged
CG
1mo ago
+792-16

Fixes #25082

Problem

A header parameter declared with content: application/json was serialized in the generated C# client through ClientUtils.ParameterToString(...). For a model object, ParameterToString falls through to Convert.ToString(obj, CultureInfo.InvariantCulture), which emits the model's debug ToString():

class HeaderArg {
  Path: /x
}

instead of JSON ({"path":"/x"}). This affects all C# client libraries, since they share this header serialization path: restsharp (default), httpclient, generichost, and unityWebRequest.

This is the C# counterpart of the Java bug #25055 (PR #25056) and the Python bug #25067 (PR #25068).

Fix

Mirror the existing queryIsJsonMimeType mechanism (which already does exactly this for query params):

  • Engine: add a shared CodegenParameter.headerIsJsonMimeType flag, set in DefaultCodegen.fromParameter via the already-existing isJsonMimeType(contentType) helper. (This is the same small engine addition proposed in #25056; if that merges first, this can be de-duped.)
  • Templates: the C# api.mustache templates serialize JSON-content headers as JSON instead of via ParameterToString, keeping existing behavior for regular headers:
    • restsharp, httpclient, unityWebRequest (Newtonsoft): a new ASCII-safe ClientUtils.ParameterToJsonString(...) helper (uses StringEscapeHandling.EscapeNonAscii).
    • generichost (System.Text.Json): JsonSerializer.Serialize(value, _jsonSerializerOptions), consistent with how it already serializes request bodies.

Generated code for a JSON-content header now looks like:

// restsharp / httpclient / unityWebRequest
localVarRequestOptions.HeaderParameters.Add("X-Json-Arg", Org.OpenAPITools.Client.ClientUtils.ParameterToJsonString(xJsonArg)); // header parameter
// generichost
httpRequestMessageLocalVar.Headers.Add("X-Json-Arg", JsonSerializer.Serialize(xJsonArg, _jsonSerializerOptions));

while a regular header is unchanged (ParameterToString(xPlainArg)).

Tests

  • Added 3_1/csharp/json-header-content.yaml (a JSON-content header + a plain header).
  • Added testJsonContentHeaderUsesJsonSerialization (restsharp) and testJsonContentHeaderUsesJsonSerializationGenericHost to CSharpClientCodegenTest, asserting the JSON header is JSON-serialized and the plain header is not.

Verification

  • CSharpClientCodegenTest — both new tests pass (Tests run: 2, Failures: 0).
  • Generated a client from the fixture for all four libraries and confirmed the header serialization code; restsharp, httpclient, and generichost outputs compile with dotnet build (0 errors). unityWebRequest output generates the expected code (requires the Unity SDK to compile).
  • Regenerated samples: the only change is the new ClientUtils.ParameterToJsonString helper added to the Newtonsoft-based generated clients.

PR checklist

  • Read the contribution guidelines.
  • Ran ./mvnw clean package for the generator and regenerated the affected samples with ./bin/generate-samples.sh bin/configs/csharp*.yaml; committed all changed files.
  • Targeting master.

cc C# technical committee: @mandrean @shibayan @Blackclaws @lucamazzanti


Summary by cubic

Fixes the C# generator so header parameters declared with content: application/json serialize as JSON instead of the model's debug ToString() output, which affected all C# client libraries.

Adds a headerIsJsonMimeType flag to CodegenParameter, set in DefaultCodegen.fromParameter for both JSON and vendor +json media types, mirroring the existing query-parameter mechanism.

  • The restsharp, httpclient, and unityWebRequest templates use a new ClientUtils.ParameterToJsonString helper for JSON-content headers; generichost uses JsonSerializer.Serialize(value, _jsonSerializerOptions). Regular headers keep using ParameterToString.
  • ParameterToJsonString serializes directly with JsonConvert.SerializeObject and escapes every character below U+0020 or at/above U+007F as \uXXXX to keep header values free of control characters.
  • Adds a 3.1 fixture and regression tests for the restsharp and generichost backends covering JSON, vendor +json, and plain headers.