Skip to content

.Net OpenApi - JsonStringEnumConverter Enums should explicitly be generated as string type (to be rendered correctly by SwaggerUI) #62022

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
1 task done
steint23 opened this issue May 20, 2025 · 4 comments
Open
1 task done

.Net OpenApi - JsonStringEnumConverter Enums should explicitly be generated as string type (to be rendered correctly by SwaggerUI) #62022

steint23 opened this issue May 20, 2025 · 4 comments
Labels
area-minimal Includes minimal APIs, endpoint filters, parameter binding, request delegate generator etc feature-openapi

Comments

@steint23
Copy link

Is there an existing issue for this?

  • I have searched the existing issues

Describe the bug

When using SwaggerUI with the built-In OpenAPI interface in .Net 9, enum members are not displayed in the Schemas section.

OpenAPI generates the enum schema:

      "MyStatus": {
        "enum": [
          "MyStatus1",
          "MyStatus2",
          "MyStatus3"
        ]
      },

In SwaggerUI enum members are not displayed in the Schemas section:

Image

Expected Behavior

OpenAPI should generate the schema with type explicitly set to "string":

      "MyStatus": {
        "enum": [
          "MyStatus1",
          "MyStatus2",
          "MyStatus3"
        ],
        "type": "string"
      },

... in order to be rendered correctly by SwaggerUI.

I assume "type": "string" is missing, because SwaggerGen creates the schema exactly like that.
Should JsonStringEnumConverter enums not explicitly be documented in OpenAPI Spec as string type anyway?

Steps To Reproduce

Brand new .NET 9 Web API from template, with OpenAPI enabled.

Define the enum:

[JsonConverter(typeof(JsonStringEnumConverter<MyStatus>))]
public enum MyStatus
{
    MyStatus1,
    MyStatus2,
    MyStatus3
}

Add enum property to the WeatherForecast model:

    public class WeatherForecast
    {
        ... other properties
        public MyStatus Status { get; set; }
    }

Nuget Package "Swashbuckle.AspNetCore.SwaggerUI"

                app.UseSwaggerUI(options =>
                {
                    options.SwaggerEndpoint("/openapi/v1.json", "My API v1");
                });

Launch app
Look at /swagger/index.html
Observe MyStatus in the Schemas section.

Exceptions (if any)

No response

.NET Version

9.0.204

Anything else?

Scalar can deal with the current OpenAPI generator output, enum members are displayed. But Scalar lacks OpenIdConnect support, which makes it currently unusable by our project.
@github-actions github-actions bot added the needs-area-label Used by the dotnet-issue-labeler to label those issues which couldn't be triaged automatically label May 20, 2025
@steint23 steint23 changed the title .Net OpenApi - JsonStringEnumConverter Enums should explicitly be generated as string type .Net OpenApi - JsonStringEnumConverter Enums should explicitly be generated as string type (to be rendered correctly by SwaggerUI) May 20, 2025
@martincostello martincostello added feature-openapi area-minimal Includes minimal APIs, endpoint filters, parameter binding, request delegate generator etc and removed needs-area-label Used by the dotnet-issue-labeler to label those issues which couldn't be triaged automatically labels May 20, 2025
@steint23
Copy link
Author

Could you guide me on how to accomlish adding "type": "string" into the enum Schema by using an appropriate SchemaTransformer?

@steint23
Copy link
Author

Here is SchemaTransformer that would accomplish this:

    /// <summary>
    /// Applies string type to the OpenApi enum schema (so SwaggerUI can render it appropriately)
    /// </summary>
    internal sealed class StringEnumSchemaTransformer : IOpenApiSchemaTransformer
    {
        public Task TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext context, CancellationToken cancellationToken)
        {
            var type = context.JsonTypeInfo.Type;
            if (type.IsEnum)
            {
                schema.Type = nameof(String).ToLower();
            }

            return Task.CompletedTask;
        }
    }

@steint23
Copy link
Author

steint23 commented May 21, 2025 •
edited
Loading

From the OpenAPI Documentation perspective in general, would it still not be appropriate to provide the string type in enum schema out of the box if JsonStringEnumConverter is involved?

@robertcoltheart
Copy link

robertcoltheart commented May 23, 2025 •
edited
Loading

We're affected by this as well, and using the transformer above doesn't help. In addition to the above, you also need to set a [JsonConverter(typeof(JsonStringEnumConverter<T>))] attribute on each enum, which isn't really feasible. Also worth noting that added a JsonStringEnumConverter to the global JSON serializer doesn't help either.

Really feel like this should be the default behavior.

Edit: I fixed this by configuring ConfigureHttpJsonOptions and AddJsonOptions in the startup to use the JSON string converter. Totally unintuitive, and documentation for this is buried. But leaving this here for other poor souls who come here looking for answers.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
area-minimal Includes minimal APIs, endpoint filters, parameter binding, request delegate generator etc feature-openapi
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@martincostello @robertcoltheart @steint23