Duplicate schemas due to different example

[MeikelLP]

Situation

I have multiple endpoints with different response models.

Some of the models have a property of type PromptType which is an enum.

The endpoints define an example each but the properties of the model may not have the same enum value.

This causes aspnetcore / openapi to generated unique enum definitions just because they have different exampels:

      "PromptType__op74F6A64CBF4E": {
        "enum": [
          "Chat",
          "Summarization",
          "Extraction",
          "CodeGeneration",
          "Classification",
          "VisionAnalysis"
        ],
        "type": "string",
        "example": "Summarization"
      },
      "PromptType__opF00923BF2CD7": {
        "enum": [
          "Chat",
          "Summarization",
          "Extraction",
          "CodeGeneration",
          "Classification",
          "VisionAnalysis"
        ],
        "type": "string",
        "example": "Chat"
      },

I was able to "merge" these definitions via a DocumentTransformer but sadly I cannot update the old references as these properties are init-only.

I define these examples using FastEndpoints:

// endpoint 1
s.RequestExamples.Add(new RequestExample(new SendPromptApiRequest("abc123def456", "xyz789uvw012", "Summarize this document", PromptType.Summarization)));
// endpoint 2
s.RequestExamples.Add(new RequestExample(new StreamPromptApiRequest("abc123def456", "xyz789uvw012", "Write a short introduction about digital twins", PromptType.Chat)));

Question

Is it the right way to modify the document afterwards? For me this might be correct but still a bit hacky. I'd like to know if I'm doing something wrong in my setup.

[tk1475]

The __op<hash> names don't come from ASP.NET Core. They're generated by FastEndpoints' OpenAPI integration (CreateOperationSchemaVariantRefId in SharedContext.cs).

When an endpoint has a request example, FastEndpoints takes the first example's property values and sets them as example on each property schema (OperationTransformer.Requests.cs). PromptType is a $ref. To avoid writing an example into the shared component, it clones the component into a per-operation variant, PromptType__op.... Later it merges variants that are identical, so endpoints with the same PromptType example end up sharing one, and different examples stay separate. So your setup isn't wrong. This is how the integration currently behaves, and it's worth raising on the FastEndpoints repo if you'd like an option to skip property-level examples for $ref/enum properties.

About post-processing: you don't need to mutate the init-only reference. Replace the dictionary entry that holds it instead. That's also what FastEndpoints does internally (schema.Properties[propName] = localized). Roughly:

static void Rewire(IOpenApiSchema? s, OpenApiDocument doc, Dictionary<string, string> aliases)
{
    if (s is not OpenApiSchema schema) return; // skip refs, their targets get visited separately
    if (schema.Properties is { } props)
        foreach (var name in props.Keys.ToList())
        {
            if (props[name] is OpenApiSchemaReference r && aliases.TryGetValue(r.Reference.Id!, out var target))
                props[name] = new OpenApiSchemaReference(target, doc);
            else
                Rewire(props[name], doc, aliases);
        }
    Rewire(schema.Items, doc, aliases);
}

Build aliases ("PromptType__op74F6..." -> "PromptType") from doc.Components.Schemas. Make sure PromptType itself exists (copy one variant with Example = null if it doesn't). Then run Rewire over every component schema and every request/response content.Schema, and delete the variants at the end. Register your transformer after FastEndpoints' own so the variants already exist when it runs.

[MeikelLP]

Thanks for the explanation! I will raise a ticket at FastEndpoints about this

Edit:
Issue has been acknowledged and is fixed in the latest beta: FastEndpoints/FastEndpoints#1193