[docs]: Document that System.Text.Json based serializer doesn't respect [EnumMember]

[jnv]

Describe the bug

I have a schema which includes an enum with JsonStringEnumConverter and a member annotated with EnumMember to supply an alternate value for de/serialization:

[JsonConverter(typeof(JsonStringEnumConverter))]
public enum JsonConverterAnnotatedEnum
{
    Value1 = 2,
    Value2 = 4,
    [EnumMember(Value = "X-foo")]
    X = 8
}

Expected behavior

The resulting JSON schema should honor value of EnumMember, i.e.:

{
  "type": "string",
  "enum": [
    "Value1",
    "Value2",
    "X-foo"
  ]
}

Actual behavior

EnumMember attribute is ignored and the enum name is used instead in the resulting schema:

{
  "type": "string",
  "enum": [
    "Value1",
    "Value2",
    "X"
  ]
}

Steps to reproduce

This can be reproduced using SwaggerGen's tests (in fact, the tests for Newtonsoft.Json based serializer already cover this use case).

Here is an example commit modifying the tests: 493e563

1. Add [EnumMember(Value = "X-foo")] attribute to JsonConverterAnnotatedEnum in Swashbuckle.AspNetCore.SwaggerGen.Test
2. Modify the GenerateSchema_HonorsSerializerAttribute_StringEnumConverter in test/Swashbuckle.AspNetCore.SwaggerGen.Test/SchemaGenerator/JsonSerializerSchemaGeneratorTests.cs to assert X-foo value
3. Run the Swashbuckle.AspNetCore.SwaggerGen.Test project

Exception(s) (if any)

No response

Swashbuckle.AspNetCore version

8.0.0

.NET Version

9.0.202

Anything else?

This issue was previously fixed in #589 for Newtonsoft.Json serializer. So it seems like a missing feature parity in System.Text.Json-based serializer.

[martincostello]

I would argue this isn't a bug as [EnumMember] isn't a native feature of System.Text.Json: dotnet/runtime#74385 (comment)

The native option, which shouldn't require us to do anything special, is [JsonStringEnumMemberName]. If that doesn't work out-of-the-box, then that would be a bug.

We might be open to adding support for [EnumMember] to support parity, but it would be preferable (because less to maintain/support) to not do so if [JsonStringEnumMemberName] just works.

[jnv]

Just after submitting this bug I found out about JsonStringEnumMemberName and I agree it's a better option.

I tried it in my fork (just had to upgrade System.Text.Json dependency in SwaggerGen.Test) and can confirm it works. I think it's worth documenting this difference though?

[martincostello]

I think it's worth documenting this difference though

Makes sense to me!