net10: a second IFormFile endpoint erases the Issue #216 file-part description document-wide

[avgalex]

Found while working on #232 (PR #233). Pre-existing, unrelated to that change.

Summary

On net10.0, adding a second endpoint that binds an IFormFile erases the Issue #216 file-part documentation (Allowed content types: …, Maximum file size: … bytes) from the whole document — including the first endpoint, which documented correctly when it was alone.

Affects MicroElements.AspNetCore.OpenApi.FluentValidation (native Microsoft.AspNetCore.OpenApi). net9.0 is not affected. Swashbuckle and NSwag are not affected.

Repro

Start from the package's test host, which has one upload endpoint:

app.MapPost("/api/upload", ([FromForm] UploadImageRequest request) => Results.Ok()).DisableAntiforgery();
// UploadImageRequest { IFormFile File }
// validator: RuleFor(x => x.File).NotNull().FileContentType("image/jpeg", "image/png").MaxFileSize(2 * 1024 * 1024);

/openapi/v1.json correctly contains:

"IFormFile": {
  "type": "string",
  "format": "binary",
  "description": "Allowed content types: image/jpeg, image/png. Maximum file size: 2097152 bytes."
}

Now add any second endpoint whose bound type contains an IFormFile — no validator, no [FromForm] attribute subtleties, a plain minimal API is enough:

public class SecondUploadRequest { public IFormFile Doc { get; set; } = default!; }

app.MapPost("/api/upload2", ([FromForm] SecondUploadRequest request) => Results.Ok()).DisableAntiforgery();

The component becomes:

"IFormFile": { "type": "string", "format": "binary" }

Both description notes are gone from the entire document. The existing test Issue216SpikeTests.FileContentType_And_MaxFileSize_Are_Documented_For_Upload_Endpoint fails.

Root cause

IFormFile is a single shared component per document. With one usage, the file property of UploadImageRequest is still an inline concrete OpenApiSchema when FluentValidationSchemaTransformer runs, so the FileContentType/MaxFileSize rules can write context.Property.Description, and the mutated instance is what later becomes the component.

With a second usage, Microsoft.AspNetCore.OpenApi promotes IFormFile to a component before the schema transformer reaches UploadImageRequest.file. The property is then an OpenApiSchemaReference, OpenApiSchemaCompatibility.GetProperty returns null, and OpenApiRuleContext.Property hands back a detached throwaway OpenApiSchema — the description is written to an object that is never serialized. This is the $ref contract from #176; the new part is that the number of usages elsewhere in the document decides whether a given endpoint gets documented.

Notes

• Any fix has to decide what a shared component should say when two endpoints allow different media types or sizes. Writing the union onto the component is wrong; writing a description sibling next to the $ref (legal in OpenAPI 3.1) keeps it per-usage and is probably the right direction.
• The machine-readable encoding.contentType (also from Add support for media types #216) is not affected — it lives on the media type, not the schema, and stays correct in this scenario.
• PR fix(#232): apply FluentValidation rules to controller [FromForm] bodies in the AspNetCore.OpenApi transformer #233 works around this in the test host by isolating its multipart fixture into a second OpenAPI document, since components are per-document.

[avgalex]

Investigated and attempted a fix. The fix is not going in yet — it traded this bug for several others — but the investigation corrected the root cause stated above and mapped out what any fix has to satisfy. Recording it here so the next attempt starts from facts.

The mechanism is not what this issue originally said

The text above guessed that the note is dropped because the property is an OpenApiSchemaReference by the time the rule runs. That is wrong. Verified with an object-identity probe (a temporary IOpenApiSchemaTransformer + IOpenApiDocumentTransformer reading Components.Schemas while generation is in flight):

Microsoft.AspNetCore.OpenApi builds one schema instance per type. With a single IFormFile usage, the instance a schema transformer decorates is the one that gets serialized, so the note appears and everything looks correct. With a second usage the framework keeps a single shared IFormFile component and the decorated copy is discarded. Hence:

• with two endpoints and only one carrying rules → the note disappears from the whole document;
• with two endpoints both carrying rules → the surviving component advertises the other endpoint's restrictions, which is worse than missing.

Confirmed on clean master (8b41798): net10.0 fails, net9.0 passes. A plain minimal API is enough — no controllers, no [FromForm] subtleties:

public class SecondUploadRequest { public IFormFile Doc { get; set; } = default!; }
app.MapPost("/api/upload2", ([FromForm] SecondUploadRequest r) => Results.Ok()).DisableAntiforgery();

What was tried, and why it was rejected

Moving the note out of the schema rules (FileContentType / FileSize in the native backend's DefaultFluentValidationRuleProvider) and into FluentValidationOperationTransformer, where the part is already a $ref, writing the note on the reference itself — legal next to $ref in OpenAPI 3.1.

That does fix the reported symptom, and a fixture with three IFormFile endpoints in one document each kept its own note. An adversarial review pass then found 14 confirmed defects. The ones that make the approach unshippable as written:

1. OpenAPI 3.0 output on net10. A description sibling next to $ref is only legal in 3.1. An app configured with OpenApiVersion = OpenApi3_0 loses the note entirely — a regression for single-upload apps, which document correctly today.
2. The hazard just moves up one level. GetFormPartContainer resolves the body $ref through context.Document.Components.Schemas[refId] and mutates that component. It is document-wide, not per-usage. If the same DTO is also reachable through a JSON schema path (request body, nested property, or response) the component entry is replaced mid-generation and the note is lost again — silently, no log, no exception. The converse leak is real too: a JSON body referencing the DTO carries the multipart note.
3. Everything the schema rules did for free is gone. Removing them broke INameResolver-renamed parts ([JsonPropertyName] — the UseDocumentFilter does not put the same properties as the OperationFilter #230 class), nested form DTOs, allOf bodies, note ordering, multi-validator behavior, and the ability to override or suppress the rule — all of which diverge from the Swashbuckle and NSwag backends.
4. Dotted flattened part keys pick up an unrelated root member's note, because the name matcher ignores separators and the new path lacked the dotted-key filter its sibling method has (the same class as the blocker fixed in fix(#232): apply FluentValidation rules to controller [FromForm] bodies in the AspNetCore.OpenApi transformer #233).

Constraints on any future fix

• The note must be per usage. There is no per-usage schema object on net10: both #/components/schemas/IFormFile and the form DTO component are document-wide, and the media-type schema is a bare $ref.
• A $ref sibling is the only per-usage slot, and it exists only in OpenAPI 3.1. A 3.0 path has to keep working through the schema rules, so the two cannot simply be swapped.
• Whatever writes the note must keep the schema rules' behavior for naming, nesting, ordering, overridability and multi-validator mode, or reimplement all of it.
• encoding.<part>.contentType is written on the operation, is per-usage, and is correct today in every one of these scenarios. Only the human-readable note is affected, and only the size limit has no machine-readable equivalent.

Contributions welcome — the analysis above should save the next attempt the two rounds it cost here.